v1

latestOpenAPI 3.0.02026-07-26492143.5 KB

Sessions

List sessions

List sessions for an agent with cursor-based pagination, optional filtering, and search.

get/agents/{agent_id}/sessions

Path parameters

agent_idstring required

ID of the agent whose sessions to list.

Query parameters

page_sizeinteger

Number of sessions to return per page. Defaults to 20, maximum 100.

cursorstring

Cursor for the next page of results. Use the next_cursor value from a previous response.

searchstring

Free-text search query to filter sessions by name or content. Also accepted as search_query.

sort_orderstring

Sort order for the results (e.g. newest or oldest).

typestring

Filter sessions by type (e.g. api, web, slack).

state'processing' | 'completed' | 'failed' | 'queued' | 'idle'

Filter sessions by state.

creator_user_idstring

Filter sessions by the user who created them.

trigger_idstring

Filter sessions by the trigger that initiated them.

Response

A paginated list of sessions.

next_cursorstring nullable

Cursor to pass as the cursor query parameter to retrieve the next page. null when there are no more results.

Example response

{
  "sessions": [
    {
      "id": "sess_xYz789AbCd",
      "agent_id": "abc123DEFghiJKL",
      "name": "Research task",
      "type": "api",
      "created_at": "2026-05-15T14:32:00Z",
      "state": "completed",
      "agent_name": "Sales research agent",
      "usage": {
        "credit_cost": 12.5,
        "tool_credit_cost": 4,
        "flow_credit_cost": 1.5,
        "input_tokens": 18432,
        "output_tokens": 2043
      }
    }
  ],
  "next_cursor": "eyJzb3J0X3ZhbHVlIjoiMjAyNi0wNS0xNVQxNDozMjowMFoiLCJpbnRlcmFjdGlvbl9pZCI6InNlc3NfeFl6Nzg5QWJDZCIsInNvcnRfYnkiOiJuZXdlc3QifQ=="
}