With an API key: the org's sessions the key can read, newest first, at most
100 (limit, default 50), optionally only one status, each in the shape
GET /o/{org}/sessions/{session} returns (CloudRunSessionList). A key
takes only status and limit.
With a signed-in session (the console): a search across every Project in
the org, filtered by the other query parameters, in the console's browsing
shape. With selector, it resolves exactly one session by full id, unique
id prefix, or title; when it matches more than one, the answer is 409
with the candidates. These errors use {code, message}.
Authenticate with an API key or a signed-in session.
Path parameters
The org's slug or id. A caller with no role in the org gets 404.
Query parameters
Exact id, a unique id prefix, or a title. Switches the route into resolution mode.
Full-text match across title, prompt and content. Repeatable. Ignored with selector.
Only this Project (handle or id), or _ for the sessions with no Project. A handle from another org returns no rows.
Only sessions started from this surface (Session.source.kind).
consoleapimcpautomationslackgithublinearOnly sessions this API key started (key_…), through the API or MCP.
Only sessions whose tokens acted as this connected account (its exact account: an email, a QuickBooks realm id, or an MCP connection's id), as CloudRunSession.accounts lists it.
A harness as dispatched, e.g. claude or codex, or a saved agent's id or exact name for that agent's sessions only. A harness name keeps its meaning; a name two agents you can see share is 422 INVALID_BODY.
Every session today is cloud; local returns an empty list.
cloudlocalLaunch-boundary managed harnesses.
claudecodexopencodeheadlessinteractiveowner/name.
One status, or several separated by commas (failed,cancelled). A key sends one.
Lower time bound. Relative (2h, 7d) or ISO 8601.
Upper time bound. Relative (2h, 7d) or ISO 8601.
recentcostdurationDefault "recent"When true, return only count and an empty sessions.
falseMax rows to return.
50min 1max 500Opaque pagination cursor from a previous response's next_cursor.
Responses
200The sessions; for a signed-in session, the matching sessions or the one a selector resolved to.
400Malformed request.
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.
401No bearer, an unknown, revoked or expired one, or an API key on a route keys cannot call.
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.
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.
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.
409The selector matched more than one session.
AMBIGUOUS_SELECTOR39 item fields
cloudlocalDefault "cloud"Indexed short handle for prefix resolution.
Owning org; null for older sessions started outside an org.
The Project the session ran in; null for a run without one.
Launch-boundary managed harnesses.
claudecodexopencodeheadlessinteractivenullpaused is a resumable session parked between turns; needs_review finished without the proof it was asked for; cancelling appears only in the 202 answer to a cancel whose sandbox is still being released; GET reads cancelled once it is.
queuedallocatingrunningpausedinput_requiredneeds_reviewcompletedfailedcancellingcancelledexpiredWhy the run failed, as a code (HARNESS_EXITED, TOKEN_LIMIT_REACHED, MACHINE_LOST, …: RUN_FAILURES in rush/shared/runs/failures.ts); null when it did not fail or failed before codes were recorded.
completepartialfailednull0000000The person who started the run; null for older sessions with no recorded starter.
2 fields
Stored summary or last assistant text line (max 200 chars); null when there is no capture.
What the last finished turn did, written from its final message; null when it left none.
2 fields
First 6 artifact previews from the stored manifest, in upload order (no timestamps, so no recency implied).
3 item fields
0The saved agent profile this run was dispatched from, named only to a caller who can see that agent; null otherwise.
2 fields
The automation that started this run; null for a run someone started.
2 fields
Where the run came from, derived from what the run records: an automation, an org API
key through MCP or over HTTP (with the key), Slack, a GitHub review, the retired Linear
dispatch, or else a person in the console or the rush CLI (console).
2 fields
consoleapimcpautomationslackgithublinearThe API key that started an api or mcp run.
2 fields
Whether the session keeps its computer between turns; only a resumable one can be woken by an automation. Null for older rows.
ephemeralresumablenull429The 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.
A sentence for a person.
Stable machine code, e.g. AUTH_FAILED, NOT_FOUND, VALIDATION_ERROR, RATE_LIMITED, TOKEN_LIMIT_REACHED.
The machine code on routes that name it this way.