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

# Create schedule

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

Creates a schedule that runs the agent on a cron cadence. Only `cron` is accepted, as a 6-field expression firing at most once per hour: hourly `0 0 * * * *`, daily `0 0 9 * * *`, or weekly `0 0 9 * * 1`.

## Path parameters

- `agent_key` string, required — The unique routing key of the agent the schedule belongs to.

## Request body

- object
  - `agent_tag` string — Pin this schedule to a specific agent version. Omit to always use the active version.
  - `display_name` string, required — Human-readable name of the schedule.
  - `expression` string, required — 6-field cron expression (sec min hour dom month dow). Seconds and minutes must be 0, day-of-month and month must be '*'. Hour and weekday must each be a single integer or '*'; ranges, lists, steps, and named days are rejected. Accepted shapes: hourly '0 0 * * * *', daily '0 0 9 * * *' (hour 0-23), weekly '0 0 9 * * 1' (weekday 0-6). Minimum firing cadence is 1 hour.
  - `payload` PublicSchedulePayload, required
    - `input` unknown
    - `memory_entity_id` string — Optional memory store entity ID to attach to each run.
    - `metadata` object — Opaque string key/value pairs attached to every response generated by this schedule.
    - `variables` object — Template variables substituted into instructions. Supports secret values: {"secret": true, "value": "..."}.
  - `type` 'cron', required — Schedule type. Only cron is accepted; the expression must be a 6-field cron expression firing at most once per hour.

## Response `201`

Schedule created.

- object
  - `_id` string, required — ULID identifying this schedule.
  - `agent_key` string, required
  - `agent_tag` string — Pinned agent version. Omit to always run the agent's current active version.
  - `created` string, date-time, required
  - `created_by_id` string, required — ID of the API key that created the schedule.
  - `display_name` string — Human-readable name of the schedule. Omitted for schedules created before display names were required.
  - `expression` string, required — 6-field cron expression. Schedules stored before the cron-only restriction may also return an @every duration or an @at RFC3339 timestamp.
  - `generation` integer, required — Monotonic counter bumped when the schedule's firing cadence changes. Used by the consumer to skip stale in-flight triggers.
  - `is_active` boolean, required — Whether the schedule is currently firing. Legacy once schedules flip to false automatically after firing.
  - `last_triggered_at` string, date-time — Timestamp of the most recent firing, if any.
  - `payload` PublicSchedulePayload, required
    - `input` unknown
    - `memory_entity_id` string — Optional memory store entity ID to attach to each run.
    - `metadata` object — Opaque string key/value pairs attached to every response generated by this schedule.
    - `variables` object — Template variables substituted into instructions. Supports secret values: {"secret": true, "value": "..."}.
  - `trigger_count` integer, required — Total firings since creation or last expression/type change.
  - `type` 'cron' | 'once' | 'interval', required — Schedule type. Only cron can be created or updated; once and interval only appear on schedules stored before that restriction.
  - `updated` string, date-time, required
  - `updated_by_id` string — ID of the API key that last updated the schedule. Omitted until the schedule is updated.

## Other responses

- `400` — Invalid schedule type, expression, or sub-hour cadence.
- `404` — Agent (or agent version, when agent_tag is set) not found.

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/versions/1072e5ba28ab/schema)