Skip to main content
GET
List sessions

Authorizations

Authorization
string
header
required

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

Headers

x-tenant-id
string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1
x-organization-id
string

Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.

Minimum string length: 1

Query Parameters

status
enum<string>

Filter by session status. Any other value is rejected with 400.

Available options:
active,
awaiting_human,
completed,
failed,
cancelled
kind
string

Filter by one or more comma-separated public session kinds, for example kind=evaluation. Evaluations are hidden from the default list; classified platform-managed sessions are never returned.

agent_id
string<uuid>

Filter by agent id (UUID). A value that is not a UUID, including an empty one, is rejected with 400.

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 cost list rows -- each root carries its whole tree's costUsd -- 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,
not_evaluable,
evaluated,
none
limit
integer
default:100

Page size, from 1 to 1000; a value outside that range is rejected with 400. 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: 1 <= 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, sort, and limit it was issued for; valid for one hour. Later pages read the snapshot the first page was read at; once that snapshot is 55 minutes old the token is rejected with 400 and the listing must start again without page_token.

automationId
string<uuid>

Return only the sessions this automation's runs started (UUID, as returned by the automations API). A value that is not a UUID, including an empty one, is rejected with 400.

evaluationTargetSessionId
string<uuid>

Return evaluation root sessions bound to this target session, including evaluations still running. Returns manual evaluations and, where supported, historical outcome evaluation roots. Linked outcome grading roots are found through the writer's outcome history. Requires kind=evaluation when kind is present. A value that is not a UUID is rejected with 400.

sortBy
enum<string>
default:updated_at

Column the whole list is ordered by before pagination. Ties break on the session's identity, so the order is total and pages neither skip nor repeat a session. last_activity_at is absent on a session that has not run a turn; those sort as the smallest value, last when descending. status orders each status group by updated_at, most recent first when ascending. session_id compares byte by byte. Any other value is rejected with 400.

Available options:
updated_at,
created_at,
last_activity_at,
status,
session_id
sortDirection
enum<string>
default:desc

Direction of sortBy. Any other value is rejected with 400.

Available options:
asc,
desc

Response

One keyset-paginated page of unclassified public sessions matching the requested filters. Classified session trees are omitted.

One page of unclassified public sessions matching the requested filters. Classified session trees are never returned by this API.

sessions
object[]
required

Unclassified public sessions matching the query filters, most recently updated first. Classified session trees are omitted.

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.