List sessions
Returns sessions visible to the caller in the calling organization, most recent first, filtered by any combination of status, kind, agent_id, current agent tag_ids, and external source. kind accepts a comma-separated list, while tag_ids uses AND semantics. Capped by limit (default 100, max 1000) rather than cursor-paginated. Ordinary callers receive only unclassified public trees; callers with elevated classified-data access can receive classified rows allowed by their scope.
Authorizations
A Recursion API key, created in the console under API keys.
Query Parameters
Filter by session status.
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.
Filter by agent id.
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.
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.
32Require the root session to carry this caller-defined metadata key with any value. Repeatable; every listed key must be present.
32Return only root sessions. Use this for model-cost list rows so children cannot consume the bounded page before their tree root.
Return only root sessions whose active browser handoff is awaiting a person (not already being driven or resolved). Applied before ordering and pagination.
Filter root sessions by their newest immutable evaluation verdict before pagination. evaluated matches any verdict; none matches sessions with no evaluation.
pass, fail, not_applicable, evaluated, none 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.
x <= 1000Signed 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 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.
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.