Skip to main content
GET
List sessions

Authorizations

Authorization
string
header
required

A Recursion API key, created in the console under API keys.

Query Parameters

status
string

Filter by session status.

kind
string

Filter by session kind. Accepts a comma-separated list (kind=chat,api_call) to match any of several kinds, which is how a caller selects agent sessions without RL rollouts. A kind filter never widens visibility. session_analyst rows are hidden by default; naming that kind returns them only when the caller's scope permits the classified sessions.

agent_id
string

Filter by agent id.

tag_ids
string

Comma-separated current agent tag ids, with at most 32 distinct ids. A session row's agent must carry every requested tag (AND semantics). Unknown or cross-organization ids return 404. Tags are resolved at read time, not from the session snapshot.

external_source_type
string
external_source_id
string
metadata
string[]

Exact-match filter on caller-defined session metadata as key:value, split at the first colon. Repeat the parameter to require several pairs; a session's root must carry every one (AND semantics). Children of a matching root match too, so combine with root_only to list only the roots.

Maximum array length: 32
metadata_key
string[]

Require the root session to carry this caller-defined metadata key with any value. Repeatable; every listed key must be present.

Maximum array length: 32
root_only
boolean

Return only root sessions. Use this for model-cost list rows so children cannot consume the bounded page before their tree root.

needs_user
boolean

Return only root sessions whose active browser handoff is awaiting a person (not already being driven or resolved). Applied before ordering and pagination.

evaluation_result
enum<string>

Filter root sessions by their newest immutable evaluation verdict before pagination. evaluated matches any verdict; none matches sessions with no evaluation.

Available options:
pass,
fail,
not_applicable,
evaluated,
none
limit
integer
default:100

Page size. When more rows match, the response carries next_page_token; pass it back as page_token with the same filters and limit to read the next page.

Required range: x <= 1000
page_token
string

Signed continuation token from a previous page's next_page_token. Bound to the organization and to the exact filters and limit it was issued for; valid for one hour.

Response

Response body of GET /v1/sessions. Keyset-paginated over (updated_at, id): a page is a stable window at the moment it is read, but a session updated between two page reads moves to the front of the list, so a live list may show it twice or skip it once. Ordinary callers receive only unclassified public session trees; callers with elevated classified-data access can receive classified rows allowed by their scope. Each row is a summary without the start-time snapshots; read one session for those. Token and cost totals are not included; fetch them for a batch of ids via GET /v1/sessions/usage and GET /v1/sessions/costs.

Response body of GET /v1/sessions. Keyset-paginated over (updated_at, id): a page is a stable window at the moment it is read, but a session updated between two page reads moves to the front of the list, so a live list may show it twice or skip it once. Ordinary callers receive only unclassified public session trees; callers with elevated classified-data access can receive classified rows allowed by their scope. Each row is a summary without the start-time snapshots; read one session for those. Token and cost totals are not included; fetch them for a batch of ids via GET /v1/sessions/usage and GET /v1/sessions/costs.

sessions
object[]
required

Sessions visible to the caller and matching the query filters, most recently updated first, at most limit (default 100) per page. An empty array means nothing matched. Ordinary callers receive a row only when access_policy is omitted/null on both it and its root; callers with elevated classified-data access can receive classified rows. Each row includes current evaluation eligibility and its newest immutable evaluation, when any. Rows are summaries: agent_snapshot and model_snapshot are omitted and config is an empty object; GET /v1/sessions/{session_id} returns them.

next_page_token
string

Present when more sessions match. Pass it as page_token with the same filters and limit to read the next page. Absent on the last page.