Search the org's sessions, or resolve one by selector

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

Without selector, lists sessions across every Project in the org (and those with no Project), newest first, filtered by the query parameters. With selector, 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. A caller that already has the id should read GET /o/{org}/p/_/sessions/{session} instead.

This route's errors use {code, message}.

Authenticate with an org 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). A handle from another org returns no rows.

agentstringoptional

Harness as dispatched, e.g. claude or codex.

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

paused is a resumable session parked between turns; needs_review finished without the proof it was asked for.

One ofqueuedallocatingrunningpausedinput_requiredneeds_reviewcompletedfailedcancelledexpired
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 matching sessions, or the one session 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, PLAN_REQUIRED.

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, PLAN_REQUIRED.

error_codestringoptional

The machine code on routes that name it this way.

messagestringoptional
requestIdstringoptional
404No such resource for the caller, including one that exists in an org the caller cannot see.
errorstringoptional

A sentence for a person.

codestringoptional

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

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

One ofqueuedallocatingrunningpausedinput_requiredneeds_reviewcompletedfailedcancelledexpired
promptstring | nulloptional
branchstring | nulloptional
pr_urlstring | nulloptional
errorstring | nulloptional
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.

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; null otherwise.

2 fields
idstringoptional
namestringoptional
created_atstringrequired
Format date-time
updated_atstring | nulloptional
Format date-time