client.runs in Python and client.Runs in Go.
List and inspect runs
- Dashboard
- CLI
- REST API
Open Runs and filter the
list. Open a run for its phone, its chat of steps, its timeline, its cost
and its recording.
GET /runs filters by agent_id, schedule_id, mode, status,
trigger and device_class, and searches run IDs with search. status and
trigger repeat to match several values.
Read how a run ended
A run that started can still fail later, while it waits for a phone or while it runs. Fetching a failed run returns HTTP200, so branch on status:
Stream a run
Every run has astream_url: its live events as
Server-Sent Events.
The URL carries a short-lived read-only token, so a browser can open it as is.
A server can send the API key header instead:
span or log), its data is the
frame as JSON, and its id is a resume cursor. The
stream carries the run’s spans, the model’s text as it streams
(model_delta logs), and the run’s own events, all logs:
The stream ends when the run ends. To resume after a dropped connection, send
the last event’s
id as the Last-Event-ID header. The run’s own events and
the model’s text are kept for 10 minutes, so a reader that comes back later
gets the run’s retained spans and its final run_status. Dedupe on the span ID
and phase across reconnects. With Telemetry off, the stream still carries the
run’s own events and the model’s text, live only.
To poll instead of holding a connection, page through the same events with
GET /runs/{run_id}/events?cursor=.... A live run’s page always has a
next_cursor; an ended run’s last page closes with its final run_status.
The CLI follows a run to its end with runs watch:
"input_required": true and the run’s input_request. The last line is a
summary with the run’s status, error, result_text and output:
runs watch exits with 0 when the run completed, 1 when it failed, and 7 when
it was cancelled or you stopped watching. A cancelled run’s error includes its
reason when it has one. See
Live Telemetry.
Read the run’s steps
GET /runs/{run_id}/steps lists an agent-mode run’s model steps, oldest
first: what each step sent the model, the model’s answer and tool calls, links
to the step’s screenshots, and its tokens and cost. Page with cursor and
next_cursor. The screenshot links are short-lived, so read the steps again
for fresh links.
Read the run’s script
GET /runs/{run_id}/script returns every cell the run executed, in order:
as one Python file in script, and one by one in cells, each with its
status (ok, error or running). Failed and exploratory cells are
included. A code run’s first cell is its revision’s script.
partial: true means some cells may be missing. To turn a good run into a
code agent, save the run as an agent
with from: "script".
Cancel a run
- Dashboard
- CLI
- REST API
Open the run from Runs
and cancel or stop it from its page.
Measure runs
GET /runs/metrics returns your finished runs over a window as points, one per
hour or day, on the shared
metrics contract. Each point has
runs, completed_runs, failed_runs, cancelled_runs, success_rate,
duration_p50_ms, duration_p95_ms, total_cost_microdollars and
model_steps. Split the points with group_by: agent, revision,
status, trigger, mode, schedule or device_class.
- CLI
- REST API
- A run counts in the bucket it finished in. Runs still going are not counted.
- A point’s
success_rateis completed runs over finished runs, from 0 to 1. - A run’s cost is its phone time plus the inference made under it. Phone time is billed when the session ends, so a run’s cost can land after the run does.
Next steps
Pause and follow up
Answer a paused run and send follow-ups.
Webhooks
Get each run’s lifecycle events pushed to you.