List sessions

GET /v1/sessions

Lists the sessions this key can see, newest first.

A personal key reads its owner’s sessions, including sessions a service account key created for its owner. A service account key reads only the sessions it created, whoever owns them. If the key is limited to specific agents (its Agent scope), it reads only those agents’ sessions.

The statuses filter applies after the server reads each page.

The key must have the tasks:read capability. For what each capability allows, see Keys.

Query parameters

Name	Type	Required	Default	Description
`limit`	`integer`	No	`20`	The maximum number of sessions to return. Must be between 1 and 100.
`page`	`string`	No		The `next_page` value from the previous response. Leave it out to get the first page.
`agent_id`	`string`	No		The ID of the agent whose sessions to return.
`include_archived`	`boolean`	No	`false`	Whether to include archived sessions.
`statuses`	`array<string>`	No		The statuses to return: `idle`, `running` or `terminated`. `rescheduling` is accepted for compatibility but never matches a session. To pass more than one, repeat the parameter: `statuses[]=idle&statuses[]=running`.
`created_at[gte]`	`string`	No		The earliest creation time to include, as an RFC 3339 timestamp. `created_at[gt]` (after), `created_at[lt]` (before) and `created_at[lte]` (at or before) filter the same field.
`order`	`string`	No	`desc`	Not supported. Omit it or send `desc`. Any other value returns `400`.

Response

Returns 200 with the matching sessions in data, newest first. next_page is the value to pass as page for the next page. A page can hold fewer sessions than limit, or none, and still have a next_page value. Keep requesting pages until next_page is null. prev_page is always null.

{
  "data": [
    {
      "id": "dd13d728-93e3-440a-874c-4efeb58c97e0",
      "agent": {
        "id": "6f1c2a9e-0d4b-4c57-9a3e-2b7d8e1f4c60",
        "description": "Answers questions about the sales pipeline",
        "execution_identity": {
          "type": "service_account"
        },
        "mcp_servers": [],
        "model": {
          "id": "default"
        },
        "multiagent": null,
        "name": "Research Assistant",
        "skills": [],
        "system": null,
        "tools": [],
        "type": "agent",
        "version": 1
      },
      "archived_at": null,
      "budget": null,
      "created_at": "2026-10-21T01:42:16.079Z",
      "environment_id": "env_default",
      "metadata": {},
      "outcome_evaluations": [],
      "resources": [
        {
          "id": "329409ba-f288-4b44-9c73-14a18150edee",
          "created_at": "2026-10-21T01:41:11.028Z",
          "file_id": "329409ba-f288-4b44-9c73-14a18150edee",
          "mount_path": "inputs/cities.csv",
          "type": "file",
          "updated_at": "2026-10-21T01:41:11.028Z"
        }
      ],
      "stats": {},
      "status": "idle",
      "title": "Quarterly city report",
      "type": "session",
      "updated_at": "2026-10-21T01:42:29.719Z",
      "usage": {
        "input_tokens": 12,
        "output_tokens": 318,
        "cache_read_input_tokens": 133496,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 2210,
          "ephemeral_1h_input_tokens": 0
        },
        "active_seconds": 7.331,
        "list_cost": {
          "amount": "6",
          "currency": "USD"
        }
      },
      "vault_ids": []
    }
  ],
  "next_page": null,
  "prev_page": null
}

Errors

This endpoint can return these errors as well as the common errors.

Status	`error.type`	Cause and fix
400	`invalid_request_error`	`order` is any value other than `desc`. Omit `order`.
400	`invalid_request_error`	`statuses` contains an unknown value. Send only `idle`, `running`, `terminated` or `rescheduling`.
400	`invalid_request_error`	The request includes `agent_version`, `deployment_id` or `memory_store_id`, which this API does not take. Remove them.

Example

curl -sS "$CONTEXT_BASE_URL/v1/sessions?limit=20&statuses[]=idle" -H "x-api-key: $CONTEXT_API_KEY"

for session in client.beta.sessions.list(limit=20, statuses=["idle"]):  # auto-paginates
    print(session.id, session.status, session.title)

for await (const session of client.beta.sessions.list({ limit: 20, statuses: ["idle"] })) console.log(session.id, session.status)