Get a session

GET /v1/sessions/{session_id}

Returns a session with its status and token totals.

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

Path parameters

Name	Type	Required	Default	Description
`session_id`	`string`	Yes		The ID of the session to retrieve.

Response

Returns 200 with the session object. For every field, see Sessions.

{
  "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": []
}

Errors

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

Status	`error.type`	Cause and fix
404	`not_found_error`	No session with this ID exists, or this key can’t read it. Check the session ID and the key you are using.
503	`api_error`	The session’s history is still being indexed. Retry the request shortly.

Example

curl -sS "$CONTEXT_BASE_URL/v1/sessions/dd13d728-93e3-440a-874c-4efeb58c97e0" -H "x-api-key: $CONTEXT_API_KEY"

session = client.beta.sessions.retrieve("dd13d728-93e3-440a-874c-4efeb58c97e0")
print(session.status, session.usage)

const session = await client.beta.sessions.retrieve("dd13d728-93e3-440a-874c-4efeb58c97e0")