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

# Create agent schedule

`POST /v2/agents/{agent_key}/schedules`

Creates a schedule that runs an agent automatically at specified intervals. Each execution creates a new session with the configured message and metadata.

Use schedules for automated agent workflows such as daily reports, periodic monitoring, or regular data processing. The schedule tags each created session with metadata that identifies it as a scheduled execution.

## Example request

```json
\$ curl -X POST https://api.vectara.io/v2/agents/support-agent/schedules \
-H "Authorization: Bearer YOUR_API_KEY" \c
-H "Content-Type: application/json" \
-d '{
  "key": "daily-report",
  "name": "Daily Summary Report",
  "message": [{"type": "text", "content": "Generate a summary of today's activities"}],
  "schedule": {
    "type": "interval",
    "interval": "PT24H"
  },
  "session_metadata": {
    "report_type": "daily"
  }
}'
```
A successful response includes the unique schedule key, configuration, and creation timestamp.

## Path parameters

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

## Headers

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

## Request body

- CreateAgentScheduleRequest — Request object for creating a new agent schedule.
  - `key` string — A unique key that identifies an agent schedule.
  - `name` string, required — The human-readable name of an agent schedule.
  - `description` string — Optional 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 — Whether the schedule is active upon creation.
  - `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. Defaults to 10.
  - `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.

## Response `201`

The created schedule, including the unique schedule key, interval, and timestamps.

- 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 creating schedules for this agent.
- `404` — Referenced agent not found.
- `409` — A schedule with the specified key already exists.

---

[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)