Get Session
The full session state + a cursor page of the decision trace.
after_index returns turns strictly after that turn_index; limit
(default 50, max 200) caps the page. has_more in the body signals
whether to page again.
Authorizations
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
Query Parameters
x >= 01 <= x <= 200Response
Successful Response
Full session state + a page of the ordered decision trace (GET).
Exactly the create/close body plus the trace, so a caller never has to reconcile two differently-shaped views of one session.
This session's spend in credits (0 if it had no billable turns).
direct, intent 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.
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.
The environment as frozen at create (name + kind snapshot).
Session status. Open union: new values may be added over time; clients must tolerate unknown values rather than failing on them.
open, completed, gave_up, closed, max_turns, spend_cap_reached, balance_exhausted The session's intent, frozen when it was created. A later edit to a registered task never changes it.
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.
pause_on_decide, frame_on_demand, free_running 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.
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.
True when more turns exist beyond this page (page with after_index).