레퍼런스HTTP APISessions

Session detail with projection, execution and durability

GET
/v1/sessions/{id}

Reads one session: its admission_state (whether it takes input and controls: active, pausing, paused, resuming, stopping, stopped, recovery_required, closing, closed), its status, the current revision, the execution as last observed, the number of pending requests, attention (why the session is held or slowed, if it is) and checkpoint durability. Read revision here and send it as expected_revision to pause, resume, close, terminate or decide recovery. status: needs_input and attention are computed on each read; reading changes nothing.

Scope: sessions:read (API key or cookie session).

Authorization

headerAuthorizationBearer <token>

For servers and scripts: an API key sent as an HTTP bearer token, Bearer <key>. It holds exactly the scopes it was issued with; a key issued before scopes existed holds none. It never needs the CSRF header, and it cannot manage agents, members, teams or API keys. Issue one in the web console under Settings → API keys; each operation names the scope it needs.

Scope: sessions:read

Path Parameters

id*string

The session's id.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Response Body

The session as it stands now.

application/json
  1. response
id*string
Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid
title*|

The session's name: the title it was created or renamed with, or else one derived from its first message (whitespace collapsed, cut to 80 characters with a trailing ellipsis). Null for sessions created before titles existed and for a first message with no text.

Defaultnull
agent*|

The agent the session was created for and the release it is pinned to: release_version_no is the card version that release runs, release_label the release's label (the Asia/Seoul second it was made, as 2026-10-30_14:30:28, with -2, -3, … for a later release of the agent in the same second), release_is_active whether that release is the agent's active release when read (false while it has none; a session keeps the release it started on). name is the agent's name now, not when the session started. Null for a session created without agent_release_id.

Defaultnull
agent_hidden*boolean

True when the session has an agent the caller may not use (a private agent outside the caller's teams): agent is then null, as are the agent's name and id everywhere else in this session. The session itself is shown as shared. False otherwise, including a session with no agent.

Defaultfalse
created_by*|

Who started the session: the signed-in person, or for an API key the person who created the key. It stays the same after a takeover hands the session to someone else. Null for sessions from before people were recorded and for a key with no creator.

Defaultnull
channel*|

Where the request that created the session came from: web for the console, api for an API key, slack for a chat surface. Null for an older session whose creating request cannot be told from what was recorded.

Defaultnull
slack_permalink*|

The Slack message that started the session, as the link Slack gave for it (chat.getPermalink); it opens only for someone who can read that message in Slack. Null for a session not started from Slack, one from before links were kept, or when Slack did not give a link.

Defaultnull
revision*integer
Range0 <= value <= 2147483647
admission_state*string
Value in"active""pausing""paused""resuming""stopping""stopped""recovery_required""closing""closed"
status*string

needs_input is derived when read: a running session or turn with at least one pending request a client can still answer (open, unexpired, raised by the attempt that holds the turn), or an idle session whose turn was parked on requests still open (input_wait.state: parked). It returns to running as soon as none is left, whether by an answer, the worker settling the request, expiry or the attempt losing the session, with no change to updated_at. The event stream reports both edges as status events: needs_input right after the question that opened the wait, and the status read here once the wait ends — at the answer or settlement that ended it, or within one reconciler pass when nothing was written (expiry, a lost attempt).

Value in"queued""running""needs_input""idle""failed""stopped"
input_wait?|

The requests the session waits on and the stage of that wait; null when it waits on none. waiting, parking and parked read the requests GET /v1/sessions/{id}/pending-requests lists; expired reads the parked turn's requests after the last one expired. Absent from a server older than the field.

runtime*|null
model*|

The model the session was created to run: the one named at create, else the agent release's card model, else the profile's default. Changing the session's profile sets it to the new profile's default. Null for a session from before the field whose model could not be told from its catalog entry.

repository_id*|null
repository*|

The repository the session was created against, as the session recorded it then: a later catalog change or removal does not alter it. Null for a session created without a repository.

Defaultnull
attached_repository_ids?array<>|

The catalog repositories besides repository_id the session works on: those it was created with (attached_repository_ids at create) and those its agent attached since with attach_repository. The session reaches only those of them its agent release's GitHub settings still list. Null on a session that attaches none (no agent release, or a profile whose repository_mode is none), and on one created before an omitted list meant []: every repository the release lists, besides its own, is reachable. Absent from a server older than the field.

attached_repositories?array<>

attached_repository_ids with a name for each, in id order. [] is a session confirmed to attach none; absent when the server cannot tell (a server older than the field, or a session whose attached_repository_ids is null, where the repositories of its agent release may be reachable).

extensions?array<>|

The extension bundles the session runs with, resolved once when it was created: later changes to the workspace's or agent's bundles do not reach it. [] is a session that runs with none. Null on a session created before extensions; absent from a server older than the field.

current_turn_id*|null
queued_turn_count*integer
Range0 <= value <= 9007199254740991
last_event_at*|null
activity?

What the session's newest events did, for a list card. Absent from a server older than the field.

created_at*string
Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
updated_at*string
Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
workspace_limit_mode?

The current attempt's workspace limit classification, recorded by the worker as a system event. Hard is storage enforcement, soft is best effort, unknown is unverified. Absent when no classification was recorded or on older servers; absence means unknown on both axes. This is not usage or an exceedance count.

execution*|null
checkpoint_revision*|null
pause_reason?|

Why the platform paused the session: awaiting_input while it is pausing or paused because its turn was parked on requests nobody answered. Null for a pause someone asked for, including one that took a park over, and for every other admission state. Absent from a server older than the field.

pending_request_count*integer

The requests GET /v1/sessions/{id}/pending-requests lists, counted in the same read as status, parked sessions included: status reads needs_input exactly when this is above zero and the session would otherwise read running or, parked, idle.

Range0 <= value <= 9007199254740991
attention*||||||||||null
durability*
Example Request
curl -X GET 'https://example.com/v1/sessions/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Example Response
{  "id": "0f8b6a52-3d1e-4c7a-9b2f-5e6d7c8a9b01",  "title": "Fix the flaky checkout test",  "agent": {    "id": "8f6c1d2e-4b3a-4c5d-9e8f-7a6b5c4d3e2f",    "name": "Checkout fixer",    "release_version_no": 3,    "release_label": "2026-10-11_17:00:00",    "release_is_active": true  },  "agent_hidden": false,  "created_by": {    "user_id": "1b2c3d4e-5f60-4718-8a9b-0c1d2e3f4a5b",    "display_name": "Mina Park"  },  "channel": "web",  "slack_permalink": null,  "revision": 7,  "admission_state": "active",  "status": "running",  "runtime": {    "kind": "claude_agent_sdk",    "version": "0.2.1",    "profile_id": "claude-coding-real",    "model": "claude-sonnet-5",    "permission_mode": "default"  },  "model": "claude-sonnet-5",  "repository_id": "sample-app",  "repository": {    "id": "sample-app",    "full_name": "acme/sample-app",    "branch": "main"  },  "current_turn_id": "3",  "queued_turn_count": 1,  "last_event_at": "2026-10-11T08:15:42Z",  "created_at": "2026-10-11T08:00:00Z",  "updated_at": "2026-10-11T08:15:40Z",  "execution": {    "backend": "local_docker",    "state": "running",    "observed_at": "2026-10-11T08:15:38Z"  },  "checkpoint_revision": 2,  "pending_request_count": 0,  "attention": null,  "durability": {    "last_transcript_persisted_at": "2026-10-11T08:15:41Z",    "checkpoint_committed_at": "2026-10-11T08:10:02Z",    "checkpoint_revision": 2,    "last_completed_turn_id": "2",    "last_checkpointed_turn_id": "2",    "checkpoint_pending_reason": null,    "checkpoint_fallback_revision": null,    "context_reset_turn_id": null  }}