Sign in

v

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-0926150111.7 MB
Agent Schedules

Create schedule

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.

post/v3/agents/{agent_key}/schedules

Path parameters

agent_keystring required

The unique routing key of the agent the schedule belongs to.

The unique routing key of the agent the schedule belongs to.

Request body

agent_tagstring

Pin this schedule to a specific agent version. Omit to always use the active version.

display_namestring required

Human-readable name of the schedule.

expressionstring 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.

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

Schedule created.

_idstring required

ULID identifying this schedule.

agent_keystring required
agent_tagstring

Pinned agent version. Omit to always run the agent's current active version.

createdstring date-time required
created_by_idstring required

ID of the API key that created the schedule.

display_namestring

Human-readable name of the schedule. Omitted for schedules created before display names were required.

expressionstring required

6-field cron expression. Schedules stored before the cron-only restriction may also return an @every duration or an @at RFC3339 timestamp.

generationinteger required

Monotonic counter bumped when the schedule's firing cadence changes. Used by the consumer to skip stale in-flight triggers.

is_activeboolean required

Whether the schedule is currently firing. Legacy once schedules flip to false automatically after firing.

last_triggered_atstring date-time

Timestamp of the most recent firing, if any.

trigger_countinteger 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.

updatedstring date-time required
updated_by_idstring

ID of the API key that last updated the schedule. Omitted until the schedule is updated.