Skip to main content
POST
Close Session

Authorizations

Authorization
string
header
required

Workspace API key as a bearer token: Authorization: Bearer ish_sk_live_.... Keys are workspace-scoped machine principals minted in Settings > Developers (shown once at mint). Scopes: sessions:run (create a session, submit turns, close), sessions:read (read the session and its decision trace), environments:read and environments:write (manage the workspace's registered environments), tasks:read and tasks:write (manage the workspace's registered tasks), people:read and people:write (the people the workspace can run a session for), and usage:read (the workspace's own consumption, spend limits and rate-limit budgets). A key is minted with sessions:run, sessions:read, and tasks:read by default; every other scope must be requested, people:read and usage:read included. An ish user access token also works on the same header for personal scripts.

Path Parameters

session_id
string<uuid>
required

Response

Successful Response

The full session, without its decision trace.

What create and close return: a caller that opened a session holds the same object a read would give it, so nothing has to be fetched twice to learn what was actually frozen. The TRACE is deliberately absent: turns are a paged subresource of the detail read, and a create has none yet.

accrued_credits
integer
required

This session's spend in credits (0 if it had no billable turns).

created_at
string<date-time>
required
created_by_api_key_id
string<uuid> | null
required
decision_mode
enum<string>
required
Available options:
direct,
intent
ended_at
string<date-time> | null
required

When the session left open (UTC), stamped on the first terminal transition and never moved. Null while the session is open. This is the timestamp sessions_ended usage buckets on.

ended_reason
string | null
required

Why the session ended, when that is finer than status: credits_exhausted or plan_allowance_exhausted (both end the session as balance_exhausted), or spend_cap_reached. Null for an ordinary ending. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.

environment
EnvironmentDescriptor · object
required

The environment as frozen at create (name + kind snapshot).

environment_id
string<uuid> | null
required
environment_revision
integer | null
required
environment_version_id
string<uuid> | null
required
environment_version_label
string | null
required
id
string<uuid>
required
max_turns
integer
required
status
enum<string>
required

Session status. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.

Available options:
open,
completed,
gave_up,
closed,
max_turns,
spend_cap_reached,
balance_exhausted
task
TaskSnapshot · object
required

The session's intent, frozen when it was created. A later edit to a registered task never changes it.

turn_count
integer
required
updated_at
string<date-time>
required
observation_retention
string
required

Retention window resolved at open: none, 30d, 90d, or indefinite. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.

pacing
enum<string>
required
Available options:
pause_on_decide,
frame_on_demand,
free_running
person_id
string<uuid> | null
required
person_snapshot
PersonSnapshot · object
required

The person as they were when the session was created, frozen onto the session.

This, not the live person, is what the session was run against: it stays readable and unchanged after the person is edited or deleted, which is what makes an old trace still mean something. id is the person's id at create time.

Additional keys may be present and more may be added over time; treat anything not listed here as unspecified rather than failing on it.

reasoning_effort
string
required

Deliberation budget the session was opened with: low, medium or high. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.

workspace_id
string<uuid>
required