Get sessions

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

GET /v1/agent/sessions/{id}

Agent → · All API references → · Get started →

Address	`https://api.hanzo.ai/v1/agent/sessions/{id}`
Method	`GET`
Operation	`get_agent_sessions_by_id`
Auth	`Authorization: Bearer $HANZO_API_KEY`

Returns one session with its direct child sessions and its 50 most recent events, oldest of those first. The children are those the caller may see, by the rule the session itself is read by: a member's own, and every one for an admin of the org.

Request

1 field.

Field	In	Type	Required	Description
`id`	path	string	yes	ID is the session to act on, from the path.

Response

Status	Body	Meaning
`200`	agent.sessionDetail	ok
`default`	problem-details	refused

200 body — 99 fields.

Field	In	Type	Always	Description
`account`	body	string	—
`actor`	body	string	—
`agent`	body	string	—
`base`	body	string	—
`branch`	body	string	—
`childSessions`	body	agent.sessionView[]	—	Children is the session's DIRECT children, one level down, each with its own counts.
`childSessions[].account`	body	string	—	Account is which subscription or API account under that provider served it.
`childSessions[].actor`	body	string	—	Actor is WHO this session belongs to, as "org/sub" — the same identity a run is billed under.
`childSessions[].agent`	body	string	—	Agent is the label the surface running this session calls itself by ("hanzo-dev"), up to 128 characters.
`childSessions[].base`	body	string	—	Base is the branch the run started from.
`childSessions[].branch`	body	string	—	Branch is the branch the run pushes its work to, and the only one it may write.
`childSessions[].children`	body	integer (int64)	—	Children is the DIRECT fan-out — how many sessions name this one as parent — and not the size of the subtree.
`childSessions[].createdAt`	body	string	—	CreatedAt is when the row was written, same format.
`childSessions[].cwd`	body	string	—	Cwd 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 answers "which work is this" with something that was true once.
`childSessions[].endedAt`	body	string	—	EndedAt is when it reached done or error, same format.
`childSessions[].environment`	body	string	—	Environment is where the run executes: "sandbox" for a Hanzo sandbox, or the id of the org's machine it was routed to (the same id Target carries).
`childSessions[].events`	body	integer (int64)	—	Events is how many turns the session's log holds, counted at read time.
`childSessions[].host`	body	string	—	Execution context (mission-control): the machine/repo/cwd a card shows and the run-target a session is dispatched to.
`childSessions[].id`	body	string	—	ID is the session's handle, minted here as "sess_" + 32 hex characters.
`childSessions[].kind`	body	string	—	Kind is what sort of run this session is the view of — "coding" for a coding run.
`childSessions[].lastEvent`	body	agent.lastEventView	—
`childSessions[].lastEvent.actor`	body	string	—	Actor is who produced the turn, defaulted to the calling principal when the writer named nobody.
`childSessions[].lastEvent.at`	body	string	—	At is when the turn was recorded, RFC 3339 in UTC to the second.
`childSessions[].lastEvent.kind`	body	string	—	Kind is what the turn was, from the log's closed six: message, tool-call, spawn, log, status, control.
`childSessions[].lastEvent.preview`	body	string	—	Preview 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.seq`	body	integer (int64)	—	Seq is that event's position in the session's log — monotonic from 1, per session.
`childSessions[].mode`	body	string	—	Mode is what the run may do to its repository: "build" edits, commits and pushes its branch; "plan" reads and answers with a plan, writing nothing.
`childSessions[].org`	body	string	—	Org 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[].parentSessionId`	body	string	—	ParentSessionID is the session that spawned this one, making this a subagent of it.
`childSessions[].pr`	body	string	—	PR is the address of the pull request the run proposed.
`childSessions[].progress`	body	agent.sessionProgress	—
`childSessions[].progress.activity`	body	string	—	Activity is the one line saying what the run is doing right now ("running the reaper's tests"), up to 120 characters, in the model's words.
`childSessions[].progress.at`	body	string	—	At is when this was determined, RFC 3339 in UTC to the second.
`childSessions[].progress.estimated`	body	boolean	—	Estimated says a MODEL produced this, from the run's transcript, and it may be wrong.
`childSessions[].progress.pct`	body	integer (int64)	—	Pct is how much of the run is done, 0 to 100.
`childSessions[].progress.phase`	body	string	—	Phase is what shape the run is in: running, blocked, done, error, or unknown when nothing has estimated it yet.
`childSessions[].project`	body	string	—	The readable build: the product this session built and whether its story is public (provenance.go).
`childSessions[].provider`	body	string	—	Provider is the linked AI account's provider (claude \| codex \| hanzo \| …) that served this run.
`childSessions[].published`	body	boolean	—	Published is the author's decision to let anyone read this session's story at the public build route.
`childSessions[].repo`	body	string	—	Repo is the code the session is working on, as the surface reported it.
`childSessions[].room`	body	string	—	Room is the collaborative room this run was started in (HIP-0523), empty when it came from anywhere else — a CLI, a schedule, an API call.
`childSessions[].rootSessionId`	body	string	—	RootSessionID is the top of this session's tree, inherited from the parent and shared by every node in one flow.
`childSessions[].sandbox`	body	string	—	Sandbox is the id of the sandbox the run works in ("m_" and 24 hex), the handle its terminal and its screen are opened with (/v1/sandbox/{id}/terminal, /screen).
`childSessions[].startedAt`	body	string	—	StartedAt is when the session opened, RFC 3339 in UTC to the second.
`childSessions[].status`	body	string	—	Status is one of exactly four: running, paused, done, error.
`childSessions[].target`	body	string	—	Target 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 another tenant's computer.
`childSessions[].taskRunId`	body	string	—	TaskRunID is that workflow's particular run.
`childSessions[].taskWorkflowId`	body	string	—	TaskWorkflowID is the hanzoai/tasks durable workflow that actually EXECUTES this session — this registry is the view, control and stream layer over it.
`childSessions[].terminal`	body	string	—	Terminal is where this session can be WATCHED — the URL the machine published for its live terminal.
`childSessions[].title`	body	string	—	Title is the human line a card shows ("ship the landing page"), up to 512 characters.
`childSessions[].updatedAt`	body	string	—	UpdatedAt is the session's last-activity clock, same format.
`children`	body	integer (int64)	—
`createdAt`	body	string	—
`cwd`	body	string	—
`endedAt`	body	string	—
`environment`	body	string	—
`events`	body	integer (int64)	—
`host`	body	string	—
`id`	body	string	—
`kind`	body	string	—
`lastEvent`	body	agent.lastEventView	—
`lastEvent.actor`	body	string	—	Actor is who produced the turn, defaulted to the calling principal when the writer named nobody.
`lastEvent.at`	body	string	—	At is when the turn was recorded, RFC 3339 in UTC to the second.
`lastEvent.kind`	body	string	—	Kind is what the turn was, from the log's closed six: message, tool-call, spawn, log, status, control.
`lastEvent.preview`	body	string	—	Preview 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.seq`	body	integer (int64)	—	Seq is that event's position in the session's log — monotonic from 1, per session.
`mode`	body	string	—
`org`	body	string	—
`parentSessionId`	body	string	—
`pr`	body	string	—
`progress`	body	agent.sessionProgress	—
`progress.activity`	body	string	—	Activity is the one line saying what the run is doing right now ("running the reaper's tests"), up to 120 characters, in the model's words.
`progress.at`	body	string	—	At is when this was determined, RFC 3339 in UTC to the second.
`progress.estimated`	body	boolean	—	Estimated says a MODEL produced this, from the run's transcript, and it may be wrong.
`progress.pct`	body	integer (int64)	—	Pct is how much of the run is done, 0 to 100.
`progress.phase`	body	string	—	Phase is what shape the run is in: running, blocked, done, error, or unknown when nothing has estimated it yet.
`project`	body	string	—
`provider`	body	string	—
`published`	body	boolean	—
`recentEvents`	body	agent.eventView[]	—	RecentEvents is the 50 most recent turns, OLDEST of those first — a transcript to read down, not a feed.
`recentEvents[].actor`	body	string	—	Actor is who produced the turn.
`recentEvents[].createdAt`	body	string	—	CreatedAt is when the turn was recorded, RFC 3339 in UTC to the second.
`recentEvents[].id`	body	string	—	ID is the event's own handle, minted as "evt_" + 32 hex characters.
`recentEvents[].kind`	body	string	—	Kind 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 running surface consumes).
`recentEvents[].payload`	body	any	—	Payload 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 credentials before it was stored.
`recentEvents[].seq`	body	integer (int64)	—	Seq 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[].sessionId`	body	string	—	SessionID is the session this turn belongs to.
`repo`	body	string	—
`room`	body	string	—
`rootSessionId`	body	string	—
`sandbox`	body	string	—
`startedAt`	body	string	—
`status`	body	string	—
`target`	body	string	—
`taskRunId`	body	string	—
`taskWorkflowId`	body	string	—
`terminal`	body	string	—
`title`	body	string	—
`updatedAt`	body	string	—

Failure carries the platform error shape — see Errors.

Examples

CLI

SDK

HTTP

MCP

hanzo agent sessions get <id>

.ts

.py

.go

.rs

.java

import { Configuration, AgentApi } from 'hanzoai';

const api = new AgentApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getAgentSessionsById({ id: 'id' });

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AgentApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AgentApi(client).get_agent_sessions_by_id(id='id')

cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.AgentAPI.GetAgentSessionsById(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_client::apis::{configuration::Configuration, agent_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = agent_api::get_agent_sessions_by_id(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AgentApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new AgentApi(client).getAgentSessionsById();

curl https://api.hanzo.ai/v1/agent/sessions/<id> \
  -H "Authorization: Bearer $HANZO_API_KEY"

MCP reaches agent through the agent tool, which names its 38 operations with its own verbs — this one among them, under a name only MCP declares. describe explains any of them:

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_agents"
         }
       }
     }'

Agent API · All Hanzo APIs · Interactive reference

Was this page useful?

PreviousList tree — GET /v1/agent/sessions/{id}/tree NextList stream