Scheduled deployments

The response includes a deployment object with a populated schedule.upcoming_runs_at with the next upcoming fire times, to confirm your schedule was set correctly.

The upcoming run timestamps are based on the exact schedule configured. However, to distribute load, deployments may apply jitter of up to 10 seconds.

A maximum of 1,000 scheduled deployments is supported per organization. Contact Anthropic support if you need more.



Cron and timezone semantics

• Expression: Standard POSIX cron (minute hour day-of-month month day-of-week). You can generate and validate these cron expressions in the Claude Console.
• Timezone: IANA timezone identifier (for example, "America/Los_Angeles").
• DST: Cron schedules use literal wall-clock matching, so "0 20 * * *" in America/New_York fires at 8
  PM local time regardless of whether EST or EDT is in effect.



Deployment runs

Deployments can fail to trigger for a variety of reasons: for example, if the environment resource has been archived, or if session creation is rate-limited. Each attempt at executing a deployment generates a deployment run record, allowing you to track successes and failures independent of the session lifecycle.

Successful deployments generate active sessions, and a successful deployment run contains the associated session_id. To follow a session's lifecycle, track the session events through the event stream or webhooks.

List all deployment runs for a deployment as follows:

You can additionally filter on deployment runs with errors:

A failed run includes an error with a type describing why session creation was rejected (for example, environment_archived_error, agent_archived_error, or session_rate_limited_error).



Managing deployment lifecycle

Pause suppresses scheduled triggers on a go-forward basis; running sessions from a prior deployment run continue to execute. Manual runs through the run endpoint are still allowed while paused. Pausing sets paused_reason to {"type": "manual"}; unpausing clears it.

Unpause resumes the schedule from the next scheduled occurrence. Missed triggers are not backfilled.

Archive, unlike pause, is terminal: the schedule terminates and the deployment cannot be modified.



Failure behavior

Session creation rate-limit responses are recorded immediately as a session_rate_limited_error run without retry; the schedule attempts again at the next scheduled occurrence. Rate limits on underlying API calls within a session are handled by the session itself.

If a deployment's agent has been archived or deleted, the deployment is automatically archived in the same operation; no deployment run is recorded. If a subagent referenced by the agent has been archived, the next trigger records a failed run with error.type: "agent_archived_error" and the deployment is automatically paused so you can update the agent and resume.



Trigger a manual run

To run a deployment outside its schedule, call the run endpoint. This creates a session immediately and writes a deployment run with trigger_context.type: "manual". This allows you to test a deployment before committing to the schedule.