List Sessions

Storage and ownership

Start the example API server and create a run or precreate a session. Keep the returned session_id. Use db_id when multiple registered databases exist; selecting table requires db_id and a configured adapter. It does not create a table on demand.

The session-type query parameter is type=agent, type=team or type=workflow. JWT user isolation is opt-in; non-admin service-account PAT callers always self-scope. A supplied user_id is a filter for unscoped callers, not permission to access another owner's records. Configured authorization also requires the relevant session read, write or delete scope.

Pagination envelope

The response contains data and meta. An empty result is shaped as follows:

{"data":[],"meta":{"page":1,"limit":20,"total_pages":0,"total_count":0,"search_time_ms":0.0}}

Timing varies. data holds session summaries; the generated session_example/summary/value wrapper describes an example, not a response field. Fetch a session by ID for its type-specific details.

GET/sessions

Retrieve paginated list of sessions with filtering and sorting options. Supports filtering by session type (agent, team, workflow), component, user, and name. Sessions represent conversation histories and execution contexts.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

type?|

Type of sessions to retrieve (agent, team, or workflow). If not provided, returns all session types.

component_id?|

Filter sessions by component ID (agent/team/workflow ID)

user_id?|

Filter sessions by user ID

session_name?|

Filter sessions by name (partial match)

limit?|

Number of sessions to return per page

Default20
page?|

Page number for pagination

Default1
sort_by?|

Field to sort sessions by

Default"created_at"
sort_order?|

Sort order (asc or desc)

Default"desc"
db_id?|

Database ID to query sessions from

table?|

The database table to use

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request GET 'https://example.com/sessions'
{  "session_example": {    "summary": "Example session response",    "value": {      "data": [        {          "session_id": "6f6cfbfd-9643-479a-ae47-b8f32eb4d710",          "session_name": "What tools do you have?",          "session_state": {},          "created_at": "2025-09-05T16:02:09Z",          "updated_at": "2025-09-05T16:02:09Z"        }      ]    }  }}