List sessions
Returns unclassified public sessions in the calling organization, most recently updated first unless sortBy and sortDirection select another order, 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. Results are keyset-paginated and capped by limit (default 100, max 1000). Every page of one listing reads the same snapshot as the first page, so a session updated while a client pages is neither skipped nor repeated. Classified session trees are omitted.
Authorizations
A Recursion API key, created in the console under API keys.
Headers
Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.
1Organization 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.
1Query Parameters
Filter by session status. Any other value is rejected with 400.
active, awaiting_human, completed, failed, cancelled 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.
Filter by agent id (UUID). A value that is not a UUID, including an empty one, is rejected with 400.
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 cost list rows -- each root carries its whole tree's costUsd -- 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, not_evaluable, evaluated, none 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.
1 <= x <= 1000Signed 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.
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.
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.
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.
updated_at, created_at, last_activity_at, status, session_id Direction of sortBy. Any other value is rejected with 400.
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.
Unclassified public sessions matching the query filters, most recently updated first. Classified session trees are omitted.
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.