Hanzo
OpenapiAgents

Returns the caller org's live sessions, newest first — each with its event…

Returns the caller org's live sessions, newest first — each with its event count, its direct-child count and a one-line preview of its latest event.

GET /v1/agents/sessions

Addresshttps://api.hanzo.ai/v1/agents/sessions
MethodGET
Operationget_agents_sessions
AuthAuthorization: Bearer $HANZO_API_KEY

Returns the caller org's live sessions, newest first — each with its event count, its direct-child count and a one-line preview of its latest event. With no filter it returns ROOT sessions only, so a dashboard shows one row per flow rather than one per subagent; ?root= or ?parent= descends.

Request

5 fields.

FieldInTypeRequiredDescription
rootquerystringRoot scopes the page to one subagent tree (its root session id).
parentquerystringParent scopes the page to the direct children of one session.
statusquerystringStatus filters to running, paused, done or error.
projectquerystringProject filters to the sessions tagged with one product slug.
limitqueryintegerLimit caps the page.

Response

StatusBodyMeaning
200sessionListok

200 body — 32 fields.

FieldInTypeAlwaysDescription
sessionsbodysessionView[]Sessions is the matching sessions, each with its event and child counts and a one-line preview of its latest event.
sessions[].accountbodystringAccount is which subscription or API account under that provider served it.
sessions[].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.
sessions[].agentbodystringAgent is the label the surface running this session calls itself by ("hanzo-dev"), up to 128 characters. Required at register.
sessions[].childrenbodyintegerChildren is the DIRECT fan-out — how many sessions name this one as parent — and not the size of the subtree.
sessions[].createdAtbodystringCreatedAt is when the row was written, same format.
sessions[].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…
sessions[].endedAtbodystringEndedAt is when it reached done or error, same format.
sessions[].eventsbodyintegerEvents is how many turns the session's log holds, counted at read time.
sessions[].hostbodystringExecution context (mission-control): the machine/repo/cwd a card shows and the run-target a session is dispatched to.
sessions[].idbodystringID is the session's handle, minted here as "sess_" + 32 hex characters.
sessions[].lastEventbodylastEventView
sessions[].lastEvent.actorbodystringActor is who produced the turn, defaulted to the calling principal when the writer named nobody.
sessions[].lastEvent.atbodystringAt is when the turn was recorded, RFC 3339 in UTC to the second.
sessions[].lastEvent.kindbodystringKind is what the turn was, from the log's closed six: message, tool-call, spawn, log, status, control.
sessions[].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.
sessions[].lastEvent.seqbodyintegerSeq is that event's position in the session's log — monotonic from 1, per session.
sessions[].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.
sessions[].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.
sessions[].projectbodystringThe readable build: the product this session built and whether its story is public (provenance.go).
sessions[].providerbodystringProvider is the linked AI account's provider (claude | codex | hanzo | …) that served this run.
sessions[].publishedbodybooleanPublished is the author's decision to let anyone read this session's story at the public build route.
sessions[].repobodystringRepo is the code the session is working on, as the surface reported it.
sessions[].rootSessionIdbodystringRootSessionID is the top of this session's tree, inherited from the parent and shared by every node in one flow.
sessions[].startedAtbodystringStartedAt is when the session opened, RFC 3339 in UTC to the second.
sessions[].statusbodystringStatus is one of exactly four: running, paused, done, error.
sessions[].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…
sessions[].taskRunIdbodystringTaskRunID is that workflow's particular run.
sessions[].taskWorkflowIdbodystringTaskWorkflowID is the hanzoai/tasks durable workflow that actually EXECUTES this session — this registry is the view, control and stream layer over it.
sessions[].terminalbodystringTerminal is where this session can be WATCHED — the URL the machine published for its live terminal.
sessions[].titlebodystringTitle is the human line a card shows ("ship the landing page"), up to 512 characters.
sessions[].updatedAtbodystringUpdatedAt is the session's last-activity clock, same format.

Failure carries the platform error shape — see Errors.

Examples

hanzo agents sessions list

Agents API · All Hanzo APIs · Interactive reference

How is this guide?

On this page