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}
| Address | https://api.hanzo.ai/v1/agents/sessions/{id} |
| Method | GET |
| Operation | get_agents_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.
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 | sessionDetail | ok |
200 body — 71 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
account | body | string | — | |
actor | body | string | — | |
agent | body | string | — | |
childSessions | body | 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. A register that names none takes the calling principal. |
childSessions[].agent | body | string | — | Agent is the label the surface running this session calls itself by ("hanzo-dev"), up to 128 characters. Required at register. |
childSessions[].children | body | integer | — | 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… |
childSessions[].endedAt | body | string | — | EndedAt is when it reached done or error, same format. |
childSessions[].events | body | integer | — | 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[].lastEvent | body | 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 | — | Seq is that event's position in the session's log — monotonic from 1, per session. |
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. Empty means this session is a root — a flow of its own. |
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[].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[].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… |
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 | — | |
createdAt | body | string | — | |
cwd | body | string | — | |
endedAt | body | string | — | |
events | body | integer | — | |
host | body | string | — | |
id | body | string | — | |
lastEvent | body | 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 | — | Seq is that event's position in the session's log — monotonic from 1, per session. |
org | body | string | — | |
parentSessionId | body | string | — | |
project | body | string | — | |
provider | body | string | — | |
published | body | boolean | — | |
recentEvents | body | 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… |
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… |
recentEvents[].seq | body | integer | — | 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 | — | |
rootSessionId | 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
hanzo agents sessions get <id>import { Configuration, AgentsApi } from 'hanzoai';
const api = new AgentsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getAgentsSessionsById({ id: 'id' });from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import AgentsApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = AgentsApi(client).get_agents_sessions_by_id(id='id')cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.AgentsAPI.GetAgentsSessionsById(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, agents_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = agents_api::get_agents_sessions_by_id(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.AgentsApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new AgentsApi(client).getAgentsSessionsById();curl https://api.hanzo.ai/v1/agents/sessions/<id> \
-H "Authorization: Bearer $HANZO_API_KEY"The door reaches agents through the agents tool, which names its 36 operations with its own verbs — this one among them, under a name only the door 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_agent_conversations"
}
}
}'How is this guide?