Follow a session live

GET/o/{org}/sessions/{session}/events
View .md

A server-sent event stream of the run as it happens. Before the sandbox starts you get status events ({status}); then the harness's own events (message, tool_use, tool_result, thinking, result, error), each with an id. A session still queued gets one status event and the stream closes, so reconnect until it has started. The stream ends with done, whose data is {status, output, result}: result is the SessionAnswer, or null when the run produced none. On a session that already finished the stream sends only status and done, never the history: read that from GET …/messages or GET …/trajectory. An error without a type ({code, message}, code one of NOT_FOUND or STREAM_ERROR) ends it early. An API key receives only these events. Reconnect with Last-Event-ID (or ?cursor=) to resume after the last event you saw. Comment lines (: keepalive) keep idle connections open.

Authenticate with an API key or a signed-in session.

Path parameters

orgstringrequired

The org's slug or id. A caller with no role in the org gets 404.

sessionstringrequired

The session's full id (execution_id).

Query parameters

cursorstringoptional

Same as Last-Event-ID, for clients that cannot set headers.

Headers

last-event-idstringoptional

Resume after this event id.

Events

The response is text/event-stream: each event is an event: line naming its type and a data: line of JSON, then a blank line. The example stream carries these:

status

data
{
  "status": "allocating",
  "id": "7c1e9a4f-2b6d-4f83-a5c0-9e3d1b8f6a24"
}

done

data
{
  "status": "completed",
  "output": "runtime: guest harness completed",
  "result": {
    "text": "Pinned the clock in checkout.spec.ts.",
    "structured": null,
    "schema_valid": null
  }
}

Responses

200The event stream.

A stream of the events above.

401No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
404No such resource for the caller, including one in an org the caller is not in or a Project that is private to someone else.
errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
429The account is over its request budget, 1,800 a minute shared by the person's API keys and console on every API host (RATE_LIMITED).

The account is over its request budget, 1,800 a minute shared by the person's API keys and console on every API host (RATE_LIMITED). The error names the limit. Wait Retry-After seconds.

errorstringoptional

A sentence for a person.

codestringoptional

Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional

Used in