---
title: "Update agent schedule"
method: PATCH
path: "/v2/agents/{agent_key}/schedules/{schedule_key}"
tags: ["Agent Schedules"]
---

# Update agent schedule

`PATCH /v2/agents/{agent_key}/schedules/{schedule_key}`

Updates an existing agent schedule. All fields are optional. The update changes only the provided fields (PATCH semantics).

To pause or resume a schedule, set the `enabled` field to `false` or `true`. Updating the schedule configuration (interval or cron) reschedules future executions. Executions currently in progress are not affected.

## Path parameters

- `agent_key` string, required — A unique key that identifies an agent.
- `schedule_key` string, required — A unique key that identifies an agent schedule.

## Headers

- `Request-Timeout` integer
- `Request-Timeout-Millis` integer

## Request body

- UpdateAgentScheduleRequest — Request object for updating an existing agent schedule. All fields are optional for PATCH semantics.
  - `name` string — The human-readable name of an agent schedule.
  - `description` string — Updated description of the schedule's purpose.
  - `message` AgentInput[] — Updated input message to send to the agent on each scheduled execution.
    - union — An input that can be provided to an agent message.
      - AgentTextInput — A text input for an agent message.
        - `type` string, required — The type of input.
        - `content` string, required — The text content of the input.
      - AgentSkillInput — An input that invokes a skill by name.
        - `type` string, required — The type of input.
        - `skill_name` string, required — The name (key) of the skill to invoke.
  - `schedule` union — Configuration for when and how often the schedule executes.
    - IntervalScheduleConfiguration — Configuration for interval-based schedule execution.
      - `type` 'interval', required — The type of schedule.
      - `interval` string, required — ISO-8601 duration string specifying the interval between executions. Minimum interval is 1 hour (PT1H). Format: P[n]DT[n]H[n]M[n]S - P: Period designator (required) - T: Time designator (separates the day and time components) Only day and time components are accepted. Month and year units, such as P1M, are rejected. Common examples: - PT1H: Every 1 hour - PT6H: Every 6 hours - PT24H or P1D: Every 24 hours (daily) - P7D: Every 7 days (weekly) - P30D: Every 30 days Reference: https://en.wikipedia.org/wiki/ISO_8601#Durations
    - CronScheduleConfiguration — Configuration for cron-based schedule execution.
      - `type` 'cron', required — The type of schedule.
      - `cron_expression` string, required — Cron expression that specifies when the schedule executes. Uses standard 5-field cron format: ┌───────────── minute (0-59) │ ┌───────────── hour (0-23) │ │ ┌───────────── day of month (1-31) │ │ │ ┌───────────── month (1-12) │ │ │ │ ┌───────────── day of week (0-6, Sunday=0) │ │ │ │ │ * * * * * Special characters: - * : Any value - , : List (e.g., "1,15" for 1st and 15th) - - : Range (e.g., "1-5" for Monday-Friday) - / : Step (e.g., "*/15" for every 15 units) The schedule must not fire more frequently than once per hour (PT1H). Common examples: - "0 9 * * *": Every day at 9:00 AM - "0 9 * * 1-5": Weekdays at 9:00 AM - "0 * * * *": Every hour - "0 */6 * * *": Every 6 hours - "0 0 1 * *": First day of every month at midnight - "0 0 * * 0": Every Sunday at midnight Tool for testing: https://crontab.guru/
  - `enabled` boolean — Updated enabled status for the schedule.
  - `session_metadata` object — Updated metadata to include in each session created by this schedule.
  - `run_condition` string, nullable — Updated UserFn boolean gate that determines whether each scheduled execution creates a session. Send null to clear the gate so the schedule runs on every execution.
  - `max_executions_to_keep` integer — Updated maximum number of past execution records to keep.
  - `stall_timeout_seconds` integer — Updated number of seconds a scheduled run may go without producing output before it is considered stalled and retried. Omit to leave the current value unchanged.

## Response `200`

Updated schedule.

- AgentSchedule — An agent schedule that automates agent execution at specified intervals.
  - `key` string, required — A unique key that identifies an agent schedule.
  - `agent_key` string, required — A unique key that identifies an agent.
  - `name` string, required — The human-readable name of an agent schedule.
  - `description` string — A detailed description of the schedule's purpose.
  - `message` AgentInput[], required — The input message to send to the agent on each scheduled execution.
    - union — An input that can be provided to an agent message.
      - AgentTextInput — A text input for an agent message.
        - `type` string, required — The type of input.
        - `content` string, required — The text content of the input.
      - AgentSkillInput — An input that invokes a skill by name.
        - `type` string, required — The type of input.
        - `skill_name` string, required — The name (key) of the skill to invoke.
  - `schedule` union, required — Configuration for when and how often the schedule executes.
    - IntervalScheduleConfiguration — Configuration for interval-based schedule execution.
      - `type` 'interval', required — The type of schedule.
      - `interval` string, required — ISO-8601 duration string specifying the interval between executions. Minimum interval is 1 hour (PT1H). Format: P[n]DT[n]H[n]M[n]S - P: Period designator (required) - T: Time designator (separates the day and time components) Only day and time components are accepted. Month and year units, such as P1M, are rejected. Common examples: - PT1H: Every 1 hour - PT6H: Every 6 hours - PT24H or P1D: Every 24 hours (daily) - P7D: Every 7 days (weekly) - P30D: Every 30 days Reference: https://en.wikipedia.org/wiki/ISO_8601#Durations
    - CronScheduleConfiguration — Configuration for cron-based schedule execution.
      - `type` 'cron', required — The type of schedule.
      - `cron_expression` string, required — Cron expression that specifies when the schedule executes. Uses standard 5-field cron format: ┌───────────── minute (0-59) │ ┌───────────── hour (0-23) │ │ ┌───────────── day of month (1-31) │ │ │ ┌───────────── month (1-12) │ │ │ │ ┌───────────── day of week (0-6, Sunday=0) │ │ │ │ │ * * * * * Special characters: - * : Any value - , : List (e.g., "1,15" for 1st and 15th) - - : Range (e.g., "1-5" for Monday-Friday) - / : Step (e.g., "*/15" for every 15 units) The schedule must not fire more frequently than once per hour (PT1H). Common examples: - "0 9 * * *": Every day at 9:00 AM - "0 9 * * 1-5": Weekdays at 9:00 AM - "0 * * * *": Every hour - "0 */6 * * *": Every 6 hours - "0 0 1 * *": First day of every month at midnight - "0 0 * * 0": Every Sunday at midnight Tool for testing: https://crontab.guru/
  - `enabled` boolean, required — Whether the schedule is currently active and executing.
  - `session_metadata` object — Arbitrary metadata to include in each session created by this schedule.
  - `run_condition` string — A UserFn boolean expression that gates execution. On each scheduled execution the agent's enrichment runs first. The schedule then evaluates this expression against the enriched session context. When the expression evaluates to true, the schedule creates the session and the agent runs. When it evaluates to false, the schedule skips the execution and creates no session. The expression uses the `get()` function with JSONPath to read the enriched context: * `$.session.metadata.*` for values written by the agent's enrichment * `$.agent.metadata.*` for the owning agent's metadata An enrichment tool call's output is visible to the condition only when the call writes it to metadata via metadata_target_path. Missing paths return null. Comparing against null is falsy, so an unresolved path skips the execution. Use `get('$.path', default)` for an explicit fallback. Omit this field to run on every execution. See https://docs.vectara.com/docs/reference/userfn-language for the UserFn language reference.
  - `max_executions_to_keep` integer — Maximum number of past execution records to keep. Older records are deleted automatically when a new execution is recorded.
  - `stall_timeout_seconds` integer — The number of seconds a scheduled run may go without producing output (streamed tokens, tool calls, or other progress events). After this period, the run is considered stalled and is retried. Set this above the longest silent operation the agent performs, so an in-flight run is not retried mid-operation.
  - `last_execution_at` string, date-time, nullable — Timestamp of the most recent execution. Updated automatically after each execution. Null until the schedule executes for the first time.
  - `created_at` string, date-time, required — Timestamp when the schedule was created. Create and update responses return the current time. Later reads return `1970-01-01T00:00:00Z`.

## Other responses

- `400` — The request is malformed or invalid.
- `403` — Permissions do not allow updating this schedule.
- `404` — Agent or schedule not found.

---

[API](https://skmtc.net/vectara/apis/vectara-rest-api-v2.md) · [All operations](https://skmtc.net/vectara/apis/vectara-rest-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vectara/vectara-rest-api-v2/versions/fca567a46b3a/schema)