List sessions
Returns unclassified public sessions in the calling organization, filtered by the declared session fields. Results are keyset-paginated and capped by limit (default 100, max 1000). Pass nextCursor back as cursor with the same filters and limit. Every page of one listing reads the same snapshot as the first page. 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 public session kinds. Classified platform-managed sessions are never returned by this list.
1 - 32 elementsFilter 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.
1 - 32 elementsExact-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 rootOnly to list only the roots.
1 - 32 elementsRequire the root session to carry this caller-defined metadata key with any value. Repeatable; every listed key must be present.
1 - 32 elementsReturn 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 nextCursor; pass it back as cursor with the same filters and limit to read the next page.
1 <= x <= 1000Signed continuation token from a previous page's nextCursor. 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 cursor.
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 kindAny=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.
Unclassified public sessions matching the query filters, most recently updated first. Classified session trees are omitted.
Cursor for the next page, or null on the last page.
Total matching sessions when known; null when the snapshot cannot count them cheaply.
0 <= x <= 9007199254740991