Runs
Create a run, follow it live, read the result, cancel it, or send the agent a message while it works.
Create a run
POST /v1/runs → 202 with Location. Only task is required.
{ "task": "Extract the names and prices from the public product catalog into a CSV.", "model_id": "platform", "reasoning_effort": "high", "session_id": "as_…", "browser_id": "br_…", "workspace_id": "ws_…", "profile_id": "pf_…", "network": { "mode": "direct" }, "credential_ids": ["cred_…"], "allowed_domains": ["example.com", "*.example.com"], "integration_ids": ["int_…"], "max_turns": 20, "timeout_ms": 300000, "max_spend_usd": 1.5, "record_video": false, "judge": true, "judge_context": ["The catalog lists three products."], "output_schema": { "type": "object", "properties": { "items": { "type": "array" } }, "required": ["items"] }}| Field | Meaning |
|---|---|
task | What to do, in plain language |
model_id | platform for the operator's model, or mdl_… for a project connection; omitted, the platform model if present, else the first usable project model |
reasoning_effort | One of the levels the model connection declares (none, low, medium, high, xhigh, max); refused otherwise |
session_id | Continue a conversation with its private context — see Sessions |
browser_id | Reuse a running browser (exclusive control while the run lasts); omitted, a new one is allocated |
workspace_id | The file space the run reads and writes; omitted, one is selected or created for a new session |
profile_id | The identity the new browser starts with; a supplied browser must carry the same profile |
network | { "mode": "direct" }, { "mode": "managed", "country": "us" } or { "mode": "custom", "server", "credential_id"? } — see Network |
credential_ids | Up to 16 project login credentials the agent can type as placeholders — see Tools |
allowed_domains, blocked_domains, block_raw_ip | The navigation policy of the browser the run creates |
integration_ids | HTTP / MCP tools the agent may call — see Integrations |
max_turns | 1–40 action turns, then the verdict turn |
timeout_ms | 1000–900000 |
max_spend_usd | Stop the run with spend_limit once its priced usage passes this |
record_video | Record the new browser's page; with an existing browser the flag must agree with its setting |
judge, judge_context | A second model reading after done, weighed with up to eight ground-truth statements of ≤ 500 characters — see Results |
output_schema | An object JSON Schema (≤ 8 KiB, bounded subset); the agent must return data in that shape |
Creation accepts Idempotency-Key. The answer comes as soon as the run is recorded: queued, with browser_id: null when the run gets a new browser. Browser capacity applies behind it — when every slot is taken the run's browser waits its turn in the admission line, the run carries its place as queue_position (1 is next) and a run.waiting event marks each place it moves to; when no slot frees within the admission wait, the run ends failed with capacity_exceeded. Cancelling a run that waits takes it out of the line.
Read a run
GET /v1/runs/{id} returns the task, status, queue_position (the place in the admission line while the run waits for a browser, otherwise null), timestamps, the result (output, and data for a run with an output_schema), error, model, browser_id, session_id, workspace_id, judge_context, judgment, signals, messages[] and durable usage (requests, total, output, cache_read, cache_write tokens over every model request the run made, judge included). GET /v1/runs lists the project's runs.
Statuses: queued → running → succeeded | failed | cancelled, with cancelling between a cancel request and the terminal state.
Follow it live
GET /v1/runs/{id}/events?after=0 returns the ordered event tail with next_cursor (a sequence number). Add &stream=1 for text/event-stream: the backlog after the cursor, then live events (id = sequence, event = type, data = the event), a : ping comment every 15 s, and an end event once the run is terminal. At most 4 open streams per API key, 8 per project and 32 per server; past that the stream is refused with rate_limited (429) and Retry-After: 15, and the same events stay readable without stream=1 — the SDKs switch to that on their own.
| Event | Carries |
|---|---|
run.queued, run.running, run.cancelling, run.succeeded, run.failed, run.cancelled | Lifecycle; the terminal ones carry error when there is one |
run.waiting | position: the run's place in the admission line, each time it moves up |
run.browser | The browser the run works in |
agent.request, agent.text, agent.thinking | A model request; the agent's prose; its reasoning when the connection returns it |
agent.tool | name, tool_call_id, arguments (≤ 8000 characters; secrets travel as {{name}} placeholders, never values) |
agent.tool_result | tool_call_id, output (≤ 32768 characters), an images count, and the runtime's [notice] lines |
agent.usage | Tokens per request, with source (agent, judge, extract, compaction) |
agent.compaction, agent.trace_truncated | Transcript compaction on a connection with a declared context window; a trace record cut to 256 KiB |
run.judged | The judge's verdict |
run.message_queued, run.message_delivered, run.message_withdrawn | Mid-run messages, below |
Every event has id, sequence and created_at. A run keeps at most 512 events.
Cancel
POST /v1/runs/{id}/cancel with {} → 202. The run goes cancelling, waits for the current browser operation to settle, releases control and ends cancelled. The browser stays alive for inspection within its idle and lifetime limits; a follow-up run can reuse it.
Message the agent mid-run
POST /v1/runs/{id}/messages with { "text": "…" } (1–8000 characters) → 202 and a message record. The text is queued for the agent's next model request: it arrives beside that turn's tool outputs, after the current tool finishes. It is steering, not an interrupt.
- Only while the run is
running;conflictwhen queued, cancelling or ended — continue the session instead. - At most eight undelivered messages at once (
rate_limited). DELETE /v1/runs/{id}/messages/{mid}withdraws a message the agent has not taken yet;conflictonce it has.- The run's
messages[]carriesqueued_at,delivered_atandwithdrawn_at.
Limits
Four active runs per platform, one per session and per browser; max_turns 1–40; timeout_ms 1000–900000; 4096 output tokens for the platform model or the project connection's 256–32768 cap; 512 events per run; 1000 retained runs per project. A restart marks unfinished runs failed and never replays external actions.