Skip to main content
A schedule sends a message to an agent later, either once or on a repeat. Check a queue every morning, prepare a weekly digest, follow up in three days, that kind of thing. Timing is either once with an RFC 3339 runAt, or repeated with a standard five-field cron and an IANA timezone. After a one-time schedule fires it flips enabled to false and sets completedAt; give it new once timing if you want to reuse it. The target decides where the message lands. { "mode": "spawn" } starts a fresh thread on each fire, which keeps unrelated runs from piling into one context window. { "mode": "thread", "threadId": "..." } queues onto a thread the same agent already owns. Each fire uses the agent’s configuration as it is at that moment: its profile, roles, tools, and model. If the previous scheduled turn is still running, the next fire is skipped rather than run on top of it. Creating a schedule requires an Idempotency-Key header. The same key twice returns the original schedule; the same key with different fields is rejected. After each fire, lastStatus is fired, skipped, or failed, with lastThreadId and lastTurnId pointing at the work. A schedule that can no longer run is disabled with a disabledReason of agent_not_found, thread_not_found, or invalid_config.
Belongs to one agent · Timing is once or repeated · Target is spawn or an existing thread · Paused with enabled: false

​
Rules

  • Overlapping fires are skipped, never queued behind each other. See Rules.
  • Disabling an agent’s identity stops its schedules firing.

​
API

  • GET/POST /v1/agents/{agentId}/schedules. limit maxes out at 100 here, not 200.
  • GET/PATCH/DELETE /v1/schedules/{scheduleId}.