Runs

A run is one request to one agent. It contains the current status, output, usage, final cost, and any error.

Start new work

run = client.runs.create(
    agent="publisher/agent-name",
    input="Prepare the finished report.",
    max_cost_usd=4,
)

The default request waits for a terminal result. The API can return 202 if the work continues after that wait ends.

Continue prior work

Pass the returned session_id to a new run.

next_run = client.runs.create(
    agent="publisher/agent-name",
    input="Add a one-page executive summary.",
    session_id=run["session_id"],
    max_cost_usd=2,
)

There is no separate session resource. Each follow-up is a new run in the same session.

Run in the background

run = client.runs.create(
    agent="publisher/agent-name",
    input="Complete the full review.",
    max_cost_usd=5,
    background=True,
)

current = client.runs.retrieve(run["id"])

Use the location response header and retry-after value when a REST request returns 202.

Stream events

for event in client.runs.stream(
    agent="publisher/agent-name",
    input="Investigate the incident.",
    max_cost_usd=3,
):
    print(event["type"])

The stream uses Server-Sent Events. Reconnect with Last-Event-ID if the connection closes.

Cancel a run

cancelled = client.runs.cancel(run["id"])
print(cancelled["status"])

Completed work remains in usage and can still have a cost.

Status values

Safe retries

Send a unique Idempotency-Key with run and cancellation requests. Reusing the same key and body returns the same operation.

If you reuse the key with another body, the API returns idempotency_conflict.