List sessions
Returns unclassified public sessions in the calling organization, most recently updated 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. 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=chat,api_call. Classified platform-managed sessions are never returned by this list.
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.
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 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.
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.