Create a scheduled agent
Create a new scheduled agent that runs on a cron schedule. The agent will be triggered automatically based on the cron expression.
Request body
Human-readable name for the schedule
Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)
The prompt/instruction for the agent to execute. Required unless agent_config.skill_spec or agent_config.skills is provided.
Query mode for an agent run.
- normal: Standard user query (default).
- plan: Planning Mode. The agent researches and creates a plan, then waits for approval before execution.
- orchestrate: Orchestration Mode. The agent proposes an orchestration plan and must not start child agents until approved.
Whether the schedule should be active immediately
Agent UID to use as the execution principal for this schedule. Only valid for team-owned schedules.
Whether to create a team-owned schedule. Defaults to true for users on a single team.
Custom key/value metadata attached to a run at creation time and immutable afterward. At most 20 keys. Keys are 1-64 bytes matching [a-zA-Z0-9._-]+ (case-sensitive); values are 0-256 bytes of UTF-8 and cannot contain NUL characters. Requests with invalid metadata are rejected. A run's effective metadata is merged per key at creation: explicit request keys override keys inherited from the parent run, which override automatic keys (ticket_id and ticket_source on Linear- and Jira-triggered runs).
Response
Scheduled agent created successfully
Unique identifier for the scheduled agent
Human-readable name for the schedule
Cron expression defining when the agent runs (e.g., "0 9 * * *" for daily at 9am UTC)
Whether the schedule is currently active
The prompt/instruction for the agent to execute
Error message from the last failed spawn attempt, if any
UID of the agent that this schedule runs as
Custom key/value metadata attached to a run at creation time and immutable afterward. At most 20 keys. Keys are 1-64 bytes matching [a-zA-Z0-9._-]+ (case-sensitive); values are 0-256 bytes of UTF-8 and cannot contain NUL characters. Requests with invalid metadata are rejected. A run's effective metadata is merged per key at creation: explicit request keys override keys inherited from the parent run, which override automatic keys (ticket_id and ticket_source on Linear- and Jira-triggered runs).
Timestamp when the schedule was created (RFC3339)
Timestamp when the schedule was last updated (RFC3339)