A scheduled deployment allows an agent to kick off sessions autonomously, enabling task completion over a predictable cadence.

Create a scheduled deployment

When creating a deployment, you pass the session configurations required for execution, in addition to a schedule.

• Deployments require agent configuration and environment configuration, and optionally accept files, GitHub, memory stores, and vaults.
• Deployments also require an initial user.message event that starts the session's work.
• In the schedule, you define a cron expression and a timezone. Maximum granularity supported is at the minute level.

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.

{
 "id": "depl_01xyz",
 "status": "active",
 "paused_reason": null,
 "schedule": {
 "type": "cron",
 "expression": "0 20 * * 5",
 "timezone": "America/New_York",
 "last_run_at": null,
 "upcoming_runs_at": [
 "2026-05-09T00:00:00Z",
 "2026-05-16T00:00:00Z",
 "2026-05-23T00:00:00Z"
 ]
 }
}

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

{
 "type": "deployment_run",
 "id": "drun_01abc124",
 "deployment_id": "depl_01xyz",
 "trigger_context": { "type": "schedule", "scheduled_at": "2026-05-09T00:00:00Z" },
 "session_id": null,
 "error": {
 "type": "environment_archived_error",
 "message": "environment `env_01abc` is archived"
 },
 "agent": { "type": "agent", "id": "agent_01ghi789", "version": 3 },
 "created_at": "2026-05-09T00:00:01Z"
}

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.