Skip to main content
GET
Retrieve a session

Authorizations

Authorization
string
header
required

A gbr_pat_ access token. Scopes are recorded on the token when it is minted.

Response

Retrieve one session.

object
string
required

Always session. Names the shape, so a value can be identified without knowing which call returned it.

Allowed value: "session"
id
string
required

Ours, not yours. Use metadata to carry your own identifier.

status
enum<string>
required

idle accepts input. working is running a turn. requires_action is waiting on you — see required_actions. failed is the last turn's outcome, not a dead session.

Available options:
idle,
working,
requires_action,
failed
created_at
integer
required

Unix milliseconds.

updated_at
integer
required

Unix milliseconds. Moves on any change, including the workspace waking.

agent
object
required

What is running, and how freely.

environment
object
required

The workspace: its state, where the agent works, and the repository bound to it.

preview
object
required

Addresses for whatever the agent is serving. See preview.md.

title
string | null

A label for people. Set it yourself; nothing derives one.

source
enum<string> | null

Which door created this session. Null on sessions predating the field.

Available options:
api,
console,
cli,
null
created_by_token
string | null

The id of the access token that created it — never its secret.

parent_session_id
string | null

The session this one was branched from, or null when it was created directly. Recorded at creation and never cleared: the source may be edited or deleted afterwards and this still answers "where did this session come from", which is the first question asked when two sessions behave differently. The column has existed since the fork endpoint shipped; only the fork response could see it, so a session read back later had no way to say it was a branch.

required_actions
object[]

Everything the session is waiting on you for. Authoritative — not a replay of events, so a caller that restarted gets the same complete answer.