List sessions

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

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

orgstringrequired

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

Query parameters

selectorstringoptional

Exact id, a unique id prefix, or a title. Switches the route into resolution mode.

qarray of stringoptional

Full-text match across title, prompt and content. Repeatable. Ignored with selector.

projectstringoptional

Only this Project (handle or id), or _ for the sessions with no Project. A handle from another org returns no rows.

sourcestringoptional

Only sessions started from this surface (Session.source.kind).

One ofconsoleapimcpautomationslackgithublinear
api_keystringoptional

Only sessions this API key started (key_…), through the API or MCP.

accountstringoptional

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.

agentstringoptional

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.

kindstringoptional

Every session today is cloud; local returns an empty list.

One ofcloudlocal
harnessstringoptional

Launch-boundary managed harnesses.

One ofclaudecodexopencode
modestringoptional
One ofheadlessinteractive
modelstringoptional
repostringoptional

owner/name.

statusstringoptional

One status, or several separated by commas (failed,cancelled). A key sends one.

sincestringoptional

Lower time bound. Relative (2h, 7d) or ISO 8601.

untilstringoptional

Upper time bound. Relative (2h, 7d) or ISO 8601.

sortstringoptional
One ofrecentcostdurationDefault "recent"
countbooleanoptional

When true, return only count and an empty sessions.

Default false
limitintegeroptional

Max rows to return.

Default 50min 1max 500
cursorstringoptional

Opaque 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.
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
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
409The selector matched more than one session.
codestringrequired
One ofAMBIGUOUS_SELECTOR
messagestringrequired
candidatesarray of Sessionrequired
39 item fields
idstringrequired
kindstringoptional
One ofcloudlocalDefault "cloud"
short_idstringrequired

Indexed short handle for prefix resolution.

titlestring | nulloptional
projectstring | nulloptional
org_idstring | nulloptional

Owning org; null for older sessions started outside an org.

Format uuid
project_idstring | nulloptional

The Project the session ran in; null for a run without one.

Format uuid
agentstring | nulloptional
harnessstringoptional

Launch-boundary managed harnesses.

One ofclaudecodexopencode
harness_version_requestedstring | nulloptional
harness_version_resolvedstring | nulloptional
modelstring | nulloptional
modestring | nulloptional
One ofheadlessinteractivenull
statusstringrequired

paused 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.

One ofqueuedallocatingrunningpausedinput_requiredneeds_reviewcompletedfailedcancellingcancelledexpired
promptstring | nulloptional
branchstring | nulloptional
pr_urlstring | nulloptional
errorstring | nulloptional
error_codestring | nulloptional

Why 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.

session_capturestring | nulloptional
One ofcompletepartialfailednull
message_countintegeroptional
Default 0
input_tokensintegeroptional
Default 0
output_tokensintegeroptional
Default 0
cache_read_tokensintegeroptional
Default 0
cache_write_tokensintegeroptional
Default 0
cost_usdnumberoptional
Default 0
duration_msinteger | nulloptional
tool_call_countintegeroptional
Default 0
started_byobject | nulloptional

The person who started the run; null for older sessions with no recorded starter.

2 fields
namestring | nulloptional
avatar_urlstring | nulloptional
summarystring | nulloptional

Stored summary or last assistant text line (max 200 chars); null when there is no capture.

recapobject | nulloptional

What the last finished turn did, written from its final message; null when it left none.

2 fields
headlinestringoptional
at most 80 characters
pointsarray of stringoptional
artifactsarray of objectoptional

First 6 artifact previews from the stored manifest, in upload order (no timestamps, so no recency implied).

3 item fields
namestringrequired
sizeintegerrequired
content_typestringrequired
artifact_countintegeroptional
Default 0
agent_profileobject | nulloptional

The saved agent profile this run was dispatched from, named only to a caller who can see that agent; null otherwise.

2 fields
idstringoptional
namestringoptional
automationobject | nulloptional

The automation that started this run; null for a run someone started.

2 fields
idstringoptional
namestringoptional
sourceobjectoptional

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
kindstringrequired
One ofconsoleapimcpautomationslackgithublinear
keyobjectoptional

The API key that started an api or mcp run.

2 fields
idstringrequired
namestringrequired
persistence_modestring | nulloptional

Whether the session keeps its computer between turns; only a resumable one can be woken by an automation. Null for older rows.

One ofephemeralresumablenull
created_atstringrequired
Format date-time
updated_atstring | nulloptional
Format date-time
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