Hanzo
OpenapiAgents

Returns one session with its direct child sessions and its 50 most recent…

Returns one session with its direct child sessions and its 50 most recent events, oldest of those first.

GET /v1/agents/sessions/{id}

Addresshttps://api.hanzo.ai/v1/agents/sessions/{id}
MethodGET
Operationget_agents_sessions_by_id
AuthAuthorization: Bearer $HANZO_API_KEY

Returns one session with its direct child sessions and its 50 most recent events, oldest of those first.

Request

1 field.

FieldInTypeRequiredDescription
idpathstringyesID is the session to act on, from the path.

Response

StatusBodyMeaning
200sessionDetailok

200 body — 71 fields.

FieldInTypeAlwaysDescription
accountbodystring
actorbodystring
agentbodystring
childSessionsbodysessionView[]Children is the session's DIRECT children, one level down, each with its own counts.
childSessions[].accountbodystringAccount is which subscription or API account under that provider served it.
childSessions[].actorbodystringActor is WHO this session belongs to, as "org/sub" — the same identity a run is billed under. A register that names none takes the calling principal.
childSessions[].agentbodystringAgent is the label the surface running this session calls itself by ("hanzo-dev"), up to 128 characters. Required at register.
childSessions[].childrenbodyintegerChildren is the DIRECT fan-out — how many sessions name this one as parent — and not the size of the subtree.
childSessions[].createdAtbodystringCreatedAt is when the row was written, same format.
childSessions[].cwdbodystringCwd is the directory the session is working in NOW, not the one it started in: a linked shell moves around, and a card showing where hanzo link was run…
childSessions[].endedAtbodystringEndedAt is when it reached done or error, same format.
childSessions[].eventsbodyintegerEvents is how many turns the session's log holds, counted at read time.
childSessions[].hostbodystringExecution context (mission-control): the machine/repo/cwd a card shows and the run-target a session is dispatched to.
childSessions[].idbodystringID is the session's handle, minted here as "sess_" + 32 hex characters.
childSessions[].lastEventbodylastEventView
childSessions[].lastEvent.actorbodystringActor is who produced the turn, defaulted to the calling principal when the writer named nobody.
childSessions[].lastEvent.atbodystringAt is when the turn was recorded, RFC 3339 in UTC to the second.
childSessions[].lastEvent.kindbodystringKind is what the turn was, from the log's closed six: message, tool-call, spawn, log, status, control.
childSessions[].lastEvent.previewbodystringPreview is the first 240 bytes of the event's payload, cut without regard for the JSON inside it — it is a string to SHOW, never a value to parse.
childSessions[].lastEvent.seqbodyintegerSeq is that event's position in the session's log — monotonic from 1, per session.
childSessions[].orgbodystringOrg is the caller's OWN tenant, echoed so a client can build the public build URL (/builds/:org/:project) without a second call or a guess.
childSessions[].parentSessionIdbodystringParentSessionID is the session that spawned this one, making this a subagent of it. Empty means this session is a root — a flow of its own.
childSessions[].projectbodystringThe readable build: the product this session built and whether its story is public (provenance.go).
childSessions[].providerbodystringProvider is the linked AI account's provider (claude | codex | hanzo | …) that served this run.
childSessions[].publishedbodybooleanPublished is the author's decision to let anyone read this session's story at the public build route.
childSessions[].repobodystringRepo is the code the session is working on, as the surface reported it.
childSessions[].rootSessionIdbodystringRootSessionID is the top of this session's tree, inherited from the parent and shared by every node in one flow.
childSessions[].startedAtbodystringStartedAt is when the session opened, RFC 3339 in UTC to the second.
childSessions[].statusbodystringStatus is one of exactly four: running, paused, done, error.
childSessions[].targetbodystringTarget is the registered run-target this session is dispatched to — a machine the org claimed, resolved same-org when it was set, so it can never point at…
childSessions[].taskRunIdbodystringTaskRunID is that workflow's particular run.
childSessions[].taskWorkflowIdbodystringTaskWorkflowID is the hanzoai/tasks durable workflow that actually EXECUTES this session — this registry is the view, control and stream layer over it.
childSessions[].terminalbodystringTerminal is where this session can be WATCHED — the URL the machine published for its live terminal.
childSessions[].titlebodystringTitle is the human line a card shows ("ship the landing page"), up to 512 characters.
childSessions[].updatedAtbodystringUpdatedAt is the session's last-activity clock, same format.
childrenbodyinteger
createdAtbodystring
cwdbodystring
endedAtbodystring
eventsbodyinteger
hostbodystring
idbodystring
lastEventbodylastEventView
lastEvent.actorbodystringActor is who produced the turn, defaulted to the calling principal when the writer named nobody.
lastEvent.atbodystringAt is when the turn was recorded, RFC 3339 in UTC to the second.
lastEvent.kindbodystringKind is what the turn was, from the log's closed six: message, tool-call, spawn, log, status, control.
lastEvent.previewbodystringPreview is the first 240 bytes of the event's payload, cut without regard for the JSON inside it — it is a string to SHOW, never a value to parse.
lastEvent.seqbodyintegerSeq is that event's position in the session's log — monotonic from 1, per session.
orgbodystring
parentSessionIdbodystring
projectbodystring
providerbodystring
publishedbodyboolean
recentEventsbodyeventView[]RecentEvents is the 50 most recent turns, OLDEST of those first — a transcript to read down, not a feed.
recentEvents[].actorbodystringActor is who produced the turn.
recentEvents[].createdAtbodystringCreatedAt is when the turn was recorded, RFC 3339 in UTC to the second.
recentEvents[].idbodystringID is the event's own handle, minted as "evt_" + 32 hex characters.
recentEvents[].kindbodystringKind is what the turn IS, from a closed six: message (a model turn), tool-call, spawn (a subagent started), log, status, control (a steering command the…
recentEvents[].payloadbodyanyPayload is the turn's body, embedded as JSON rather than as a string — whatever the writer sent, up to 64 KiB, checked for well-formedness and scanned for…
recentEvents[].seqbodyintegerSeq is the turn's position in this session's log: monotonic from 1, assigned by the store inside the insert, and unique PER SESSION rather than globally.
recentEvents[].sessionIdbodystringSessionID is the session this turn belongs to.
repobodystring
rootSessionIdbodystring
startedAtbodystring
statusbodystring
targetbodystring
taskRunIdbodystring
taskWorkflowIdbodystring
terminalbodystring
titlebodystring
updatedAtbodystring

Failure carries the platform error shape — see Errors.

Examples

hanzo agents sessions get <id>

Agents API · All Hanzo APIs · Interactive reference

How is this guide?

On this page