Scheduled deployments

A scheduled deployment allows an agent to start sessions autonomously, enabling task completion over a predictable cadence. You create and manage deployments with the OMA Deployments API.

All Managed Agents API requests require the managed-agents-2026-04-01 beta header. The SDK sets the beta header automatically.

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 at least one initial event, a user.message or user.define_outcome, that starts each session’s work.
In the schedule, you define a cron expression and a timezone. Maximum granularity supported is at the minute level.

DEPLOYMENT_ID=$(
  curl --fail-with-body -sS "http://localhost:38080/v1/deployments?beta=true" \
    -H "x-api-key: $OMA_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d @- <<EOF | jq -er '.id'
{
  "name": "Weekly compliance scan",
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "initial_events": [
    {"type": "user.message", "content": [{"type": "text", "text": "Run the weekly compliance scan."}]}
  ],
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York"
  }
}
EOF
)

DEPLOYMENT_ID=$(ant beta:deployments create <<YAML | jq -er '.id'
name: Weekly compliance scan
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
initial_events:
  - type: user.message
    content:
      - type: text
        text: Run the weekly compliance scan.
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
YAML
)

deployment = client.beta.deployments.create(
    name="Weekly compliance scan",
    agent=agent.id,
    environment_id=environment.id,
    initial_events=[
        {
            "type": "user.message",
            "content": [{"type": "text", "text": "Run the weekly compliance scan."}],
        },
    ],
    schedule={
        "type": "cron",
        "expression": "0 20 * * 5",
        "timezone": "America/New_York",
    },
)

const deployment = await client.beta.deployments.create({
  name: "Weekly compliance scan",
  agent: agent.id,
  environment_id: environment.id,
  initial_events: [
    {
      type: "user.message",
      content: [{ type: "text", text: "Run the weekly compliance scan." }],
    },
  ],
  schedule: {
    type: "cron",
    expression: "0 20 * * 5",
    timezone: "America/New_York",
  },
});

var deployment = await client.Beta.Deployments.Create(new()
{
    Name = "Weekly compliance scan",
    Agent = agent.ID,
    EnvironmentID = environment.ID,
    InitialEvents =
    [
        new BetaManagedAgentsUserMessageEventParams
        {
            Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
            Content =
            [
                new BetaManagedAgentsTextBlock
                {
                    Type = BetaManagedAgentsTextBlockType.Text,
                    Text = "Run the weekly compliance scan.",
                },
            ],
        },
    ],
    Schedule = new BetaManagedAgentsScheduleParams
    {
        Type = BetaManagedAgentsScheduleParamsType.Cron,
        Expression = "0 20 * * 5",
        Timezone = "America/New_York",
    },
});

deployment, err := client.Beta.Deployments.New(ctx, anthropic.BetaDeploymentNewParams{
    Name:          "Weekly compliance scan",
    Agent:         anthropic.BetaDeploymentNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
    EnvironmentID: environment.ID,
    InitialEvents: []anthropic.BetaManagedAgentsDeploymentInitialEventParamsUnion{{
        OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
            Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
            Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
                OfText: &anthropic.BetaManagedAgentsTextBlockParam{
                    Type: anthropic.BetaManagedAgentsTextBlockTypeText,
                    Text: "Run the weekly compliance scan.",
                },
            }},
        },
    }},
    Schedule: anthropic.BetaManagedAgentsScheduleParams{
        Type:       anthropic.BetaManagedAgentsScheduleParamsTypeCron,
        Expression: "0 20 * * 5",
        Timezone:   "America/New_York",
    },
})
if err != nil {
    panic(err)
}

var deployment = client.beta().deployments().create(
    DeploymentCreateParams.builder()
        .name("Weekly compliance scan")
        .agent(agent.id())
        .environmentId(environment.id())
        .addInitialEvent(
            BetaManagedAgentsUserMessageEventParams.builder()
                .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
                .addTextContent("Run the weekly compliance scan.")
                .build()
        )
        .schedule(
            BetaManagedAgentsScheduleParams.builder()
                .type(BetaManagedAgentsScheduleParams.Type.CRON)
                .expression("0 20 * * 5")
                .timezone("America/New_York")
                .build()
        )
        .build()
);

$deployment = $client->beta->deployments->create(
    name: 'Weekly compliance scan',
    agent: $agent->id,
    environmentID: $environment->id,
    initialEvents: [
        [
            'type' => 'user.message',
            'content' => [['type' => 'text', 'text' => 'Run the weekly compliance scan.']],
        ],
    ],
    schedule: [
        'type' => 'cron',
        'expression' => '0 20 * * 5',
        'timezone' => 'America/New_York',
    ],
);

deployment = client.beta.deployments.create(
  name: "Weekly compliance scan",
  agent: agent.id,
  environment_id: environment.id,
  initial_events: [
    {
      type: "user.message",
      content: [{type: "text", text: "Run the weekly compliance scan."}]
    }
  ],
  schedule: {
    type: "cron",
    expression: "0 20 * * 5",
    timezone: "America/New_York"
  }
)

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 reflect the exact schedule configured. However, to distribute load, actual execution applies jitter of up to 15% of the interval between runs, with a minimum of 5 seconds and a maximum of 9 minutes. A maximum of 1,000 scheduled deployments is supported per organization. Contact OMA support if you need more. See the Create Deployment reference for full parameters and response schema.

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 OMA 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 8PM local time regardless of whether EST or EDT is in effect.

Wall-clock times that do not exist on a spring-forward day (such as 2 AM) are not triggered. Wall-clock times that occur twice on a fall-back day fire twice. Schedule outside the 1–3 AM local window, or use UTC, when missed or duplicate executions are unacceptable.

Set a budget on each run

Pass the optional budget object when you create or update the deployment. It takes the same shape as a session budget. The deployment copies the cap onto each session it starts, so the budget bounds every run separately rather than acting as a cumulative ceiling across runs: a deployment with a "2000" cap can spend up to about $20 on every run. A session started by the deployment behaves exactly like any other budgeted session: it pauses with budget_reached when its own list cost reaches the cap. Changing the deployment’s budget applies to runs started afterward; a session already running keeps the cap it started with, which you can change through the session itself. Unlike a session budget, a deployment’s budget can be removed with "budget": null and set again later. The following example sets a budget on an existing deployment:

cURL

curl --fail-with-body -sS "http://localhost:38080/v1/deployments/$DEPLOYMENT_ID?beta=true" \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2000", "currency": "USD"}
  }
}
EOF

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. Deployment lifecycle changes and the outcome of each scheduled run are also delivered as webhook events, listed in the Deployment events and Deployment run events tabs of Supported event types. List all deployment runs for a deployment as follows:

curl --fail-with-body -sS "http://localhost:38080/v1/deployment_runs?beta=true&deployment_id=$DEPLOYMENT_ID" \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID"

for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
):
    print(run.created_at, run.session_id or run.error.type)

for await (const run of client.beta.deploymentRuns.list({
  deployment_id: deployment.id,
})) {
  console.log(run.created_at, run.session_id ?? run.error?.type);
}

var runs = await client.Beta.DeploymentRuns.List(
    new() { DeploymentID = deployment.ID }
);
await foreach (var run in runs.Paginate())
{
    // The Error union exposes .Message directly; the discriminator is read
    // from .Json until a common .Type accessor is added.
    var outcome = run.SessionID ?? run.Error!.Json.GetProperty("type").GetString();
    Console.WriteLine($"{run.CreatedAt} {outcome}");
}

runs := client.Beta.DeploymentRuns.ListAutoPaging(ctx, anthropic.BetaDeploymentRunListParams{
    DeploymentID: anthropic.String(deployment.ID),
})
for runs.Next() {
    run := runs.Current()
    if run.SessionID != "" {
        fmt.Println(run.CreatedAt.Format(time.RFC3339), run.SessionID)
    } else {
        fmt.Println(run.CreatedAt.Format(time.RFC3339), run.Error.Type)
    }
}
if err := runs.Err(); err != nil {
    panic(err)
}

for (var run : client.beta().deploymentRuns().list(
        DeploymentRunListParams.builder()
            .deploymentId(deployment.id())
            .build()).autoPager()) {
    // The Error union does not yet expose common .type()/.message()
    // accessors; .toString() includes both.
    IO.println(run.createdAt() + " "
        + run.sessionId().orElseGet(() -> run.error().orElseThrow().toString()));
}

foreach ($client->beta->deploymentRuns->list(
    deploymentID: $deployment->id,
)->pagingEachItem() as $run) {
    $outcome = $run->sessionID ?? $run->error->type;
    echo "{$run->createdAt->format(DATE_ATOM)} {$outcome}\n";
}

client.beta.deployment_runs.list(
  deployment_id: deployment.id
).auto_paging_each do
  puts "#{it.created_at} #{it.session_id || it.error.type}"
end

You can additionally filter on deployment runs with errors:

curl --fail-with-body -sS "http://localhost:38080/v1/deployment_runs?beta=true&deployment_id=$DEPLOYMENT_ID&has_error=true" \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID" --has-error

for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
    has_error=True,
):
    print(run.created_at, run.error.type, run.error.message)

for await (const run of client.beta.deploymentRuns.list({
  deployment_id: deployment.id,
  has_error: true,
})) {
  console.log(run.created_at, run.error?.type, run.error?.message);
}

var failedRuns = await client.Beta.DeploymentRuns.List(
    new() { DeploymentID = deployment.ID, HasError = true }
);
await foreach (var failedRun in failedRuns.Paginate())
{
    var error = failedRun.Error!;
    var errorType = error.Json.GetProperty("type").GetString();
    Console.WriteLine($"{failedRun.CreatedAt} {errorType} {error.Message}");
}

failedRuns := client.Beta.DeploymentRuns.ListAutoPaging(ctx, anthropic.BetaDeploymentRunListParams{
    DeploymentID: anthropic.String(deployment.ID),
    HasError:     anthropic.Bool(true),
})
for failedRuns.Next() {
    failedRun := failedRuns.Current()
    fmt.Println(failedRun.CreatedAt.Format(time.RFC3339), failedRun.Error.Type, failedRun.Error.Message)
}
if err := failedRuns.Err(); err != nil {
    panic(err)
}

for (var run : client.beta().deploymentRuns().list(
        DeploymentRunListParams.builder()
            .deploymentId(deployment.id())
            .hasError(true)
            .build()).autoPager()) {
    IO.println(run.createdAt() + " " + run.error().orElseThrow());
}

foreach ($client->beta->deploymentRuns->list(
    deploymentID: $deployment->id,
    hasError: true,
)->pagingEachItem() as $run) {
    echo "{$run->createdAt->format(DATE_ATOM)} {$run->error->type} {$run->error->message}\n";
}

client.beta.deployment_runs.list(
  deployment_id: deployment.id,
  has_error: true
).auto_paging_each do
  puts "#{it.created_at} #{it.error.type} #{it.error.message}"
end

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). See the List Deployment Runs reference for all filter parameters and the response schema.

{
  "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"
}

To retrieve a single run by ID, call GET /v1/deployment_runs/{deployment_run_id}. A deployment_run webhook event carries the run ID as its data.id.

Managing deployment lifecycle

Each lifecycle change emits a webhook event, so you can react to a paused, unpaused, or archived deployment without polling; see the Deployment events tab. 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.

curl --fail-with-body -sS -X POST "http://localhost:38080/v1/deployments/$DEPLOYMENT_ID/pause?beta=true" \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

ant beta:deployments pause --deployment-id "$DEPLOYMENT_ID"

client.beta.deployments.pause(deployment.id)

await client.beta.deployments.pause(deployment.id);

await client.Beta.Deployments.Pause(deployment.ID);

if _, err := client.Beta.Deployments.Pause(ctx, deployment.ID, anthropic.BetaDeploymentPauseParams{}); err != nil {
    panic(err)
}

client.beta().deployments().pause(deployment.id());

$client->beta->deployments->pause($deployment->id);

client.beta.deployments.pause(deployment.id)

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

curl --fail-with-body -sS -X POST "http://localhost:38080/v1/deployments/$DEPLOYMENT_ID/unpause?beta=true" \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

ant beta:deployments unpause --deployment-id "$DEPLOYMENT_ID"

client.beta.deployments.unpause(deployment.id)

await client.beta.deployments.unpause(deployment.id);

await client.Beta.Deployments.Unpause(deployment.ID);

if _, err := client.Beta.Deployments.Unpause(ctx, deployment.ID, anthropic.BetaDeploymentUnpauseParams{}); err != nil {
    panic(err)
}

client.beta().deployments().unpause(deployment.id());

$client->beta->deployments->unpause($deployment->id);

client.beta.deployments.unpause(deployment.id)

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

curl --fail-with-body -sS -X POST "http://localhost:38080/v1/deployments/$DEPLOYMENT_ID/archive?beta=true" \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

ant beta:deployments archive --deployment-id "$DEPLOYMENT_ID"

client.beta.deployments.archive(deployment.id)

await client.beta.deployments.archive(deployment.id);

await client.Beta.Deployments.Archive(deployment.ID);

if _, err := client.Beta.Deployments.Archive(ctx, deployment.ID, anthropic.BetaDeploymentArchiveParams{}); err != nil {
    panic(err)
}

client.beta().deployments().archive(deployment.id());

$client->beta->deployments->archive($deployment->id);

client.beta.deployments.archive(deployment.id)

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, the deployment is automatically archived in the same operation. If the agent has been deleted, the next scheduled trigger detects the missing agent and automatically archives the deployment. In both cases 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. Other unrecoverable session-creation errors, such as an archived environment or vault, behave the same way: the trigger records a failed run and the deployment is automatically paused. The deployment’s paused_reason.error.type mirrors the failed run’s error.type.

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.

curl --fail-with-body -sS -X POST "http://localhost:38080/v1/deployments/$DEPLOYMENT_ID/run?beta=true" \
  -H "x-api-key: $OMA_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

ant beta:deployments run --deployment-id "$DEPLOYMENT_ID"

run = client.beta.deployments.run(deployment.id)

const run = await client.beta.deployments.run(deployment.id);

var manualRun = await client.Beta.Deployments.Run(deployment.ID);

manualRun, err := client.Beta.Deployments.Run(ctx, deployment.ID, anthropic.BetaDeploymentRunParams{})
if err != nil {
    panic(err)
}

var run = client.beta().deployments().run(deployment.id());

$run = $client->beta->deployments->run($deployment->id);

run = client.beta.deployments.run(deployment.id)

First steps

Define your agent

Configure agent environment

Delegate work to your agent

Manage agent context

Advanced orchestration

Reference

Create a scheduled deployment

Cron and timezone semantics

Set a budget on each run

Deployment runs

Managing deployment lifecycle

Failure behavior

Trigger a manual run

​Create a scheduled deployment

​Cron and timezone semantics

​Set a budget on each run

​Deployment runs

​Managing deployment lifecycle

​Failure behavior

​Trigger a manual run

Create a scheduled deployment

Cron and timezone semantics

Set a budget on each run

Deployment runs

Managing deployment lifecycle

Failure behavior

Trigger a manual run