Returns session metadata, the embedded agent snapshot, and resource list. Event history and message content are retrieved through the Event API.
Prerequisites
Endpoint and authentication configuration must be completed. For details, see Overview and authentication.
Endpoint
GET /sessions/{session_id}
Request example
Response example
Response fields
| Field | Type | Description |
|---|---|---|
id | string | Session ID, format sesn_<ULID> |
type | string | Fixed as session |
status | string | Session status: idle / running / terminated |
stop_reason | object | null | The reason the session returned to idle. A discriminated union: null (running, or idle and just created with no end reason yet) | {"type": "end_turn"} (model ended on its own) | {"type": "retries_exhausted"} (retries exhausted) | {"type": "requires_action", "pending_batch_id": "...", "pending_call_ids": [...]} (waiting for tool approval). Only meaningful when status is idle; null when running. terminated is a terminal state and the server may retain the previous value — clients should not rely on or interpret it. The requires_action branch carries a non-empty pending_batch_id and pending_call_ids; use them to locate the pending approval calls and fetch the corresponding tool_approval_request events via the Event API |
agent | object | Full agent configuration snapshot, including id/version/name/model/system/tools, etc.; session-level overrides (if any) are merged into the snapshot |
environment_id | string | The bound environment ID |
title / metadata | string / object | Session title and custom business metadata |
archived_at | string | null | Archive time; null when not archived |
created_at / updated_at | string | Creation/last update time, ISO 8601 |
request_id | string | Unique identifier for this request |
environment_variables | object | Environment variables injected into the session runtime as string key-value pairs; sandbox code can read them directly by name |
vault_ids | array of string | Bound vault ID list |
mcp_configs | array of object | Session-level MCP request headers; each item contains mcp_server_name and headers. Empty array when not configured |