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
| Address | https://api.hanzo.ai/v1/agents/sessions |
| Method | GET |
| Operation | get_agents_sessions |
| Auth | Authorization: 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.
| Field | In | Type | Required | Description |
|---|---|---|---|---|
root | query | string | — | Root scopes the page to one subagent tree (its root session id). |
parent | query | string | — | Parent scopes the page to the direct children of one session. |
status | query | string | — | Status filters to running, paused, done or error. |
project | query | string | — | Project filters to the sessions tagged with one product slug. |
limit | query | integer | — | Limit caps the page. |
Response
| Status | Body | Meaning |
|---|---|---|
200 | sessionList | ok |
200 body — 32 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
sessions | body | sessionView[] | — | Sessions is the matching sessions, each with its event and child counts and a one-line preview of its latest event. |
sessions[].account | body | string | — | Account is which subscription or API account under that provider served it. |
sessions[].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. |
sessions[].agent | body | string | — | Agent is the label the surface running this session calls itself by ("hanzo-dev"), up to 128 characters. Required at register. |
sessions[].children | body | integer | — | Children is the DIRECT fan-out — how many sessions name this one as parent — and not the size of the subtree. |
sessions[].createdAt | body | string | — | CreatedAt is when the row was written, same format. |
sessions[].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… |
sessions[].endedAt | body | string | — | EndedAt is when it reached done or error, same format. |
sessions[].events | body | integer | — | Events is how many turns the session's log holds, counted at read time. |
sessions[].host | body | string | — | Execution context (mission-control): the machine/repo/cwd a card shows and the run-target a session is dispatched to. |
sessions[].id | body | string | — | ID is the session's handle, minted here as "sess_" + 32 hex characters. |
sessions[].lastEvent | body | lastEventView | — | |
sessions[].lastEvent.actor | body | string | — | Actor is who produced the turn, defaulted to the calling principal when the writer named nobody. |
sessions[].lastEvent.at | body | string | — | At is when the turn was recorded, RFC 3339 in UTC to the second. |
sessions[].lastEvent.kind | body | string | — | Kind is what the turn was, from the log's closed six: message, tool-call, spawn, log, status, control. |
sessions[].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. |
sessions[].lastEvent.seq | body | integer | — | Seq is that event's position in the session's log — monotonic from 1, per session. |
sessions[].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. |
sessions[].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. |
sessions[].project | body | string | — | The readable build: the product this session built and whether its story is public (provenance.go). |
sessions[].provider | body | string | — | Provider is the linked AI account's provider (claude | codex | hanzo | …) that served this run. |
sessions[].published | body | boolean | — | Published is the author's decision to let anyone read this session's story at the public build route. |
sessions[].repo | body | string | — | Repo is the code the session is working on, as the surface reported it. |
sessions[].rootSessionId | body | string | — | RootSessionID is the top of this session's tree, inherited from the parent and shared by every node in one flow. |
sessions[].startedAt | body | string | — | StartedAt is when the session opened, RFC 3339 in UTC to the second. |
sessions[].status | body | string | — | Status is one of exactly four: running, paused, done, error. |
sessions[].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… |
sessions[].taskRunId | body | string | — | TaskRunID is that workflow's particular run. |
sessions[].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. |
sessions[].terminal | body | string | — | Terminal is where this session can be WATCHED — the URL the machine published for its live terminal. |
sessions[].title | body | string | — | Title is the human line a card shows ("ship the landing page"), up to 512 characters. |
sessions[].updatedAt | body | string | — | UpdatedAt is the session's last-activity clock, same format. |
Failure carries the platform error shape — see Errors.
Examples
hanzo agents sessions listimport { Configuration, AgentsApi } from 'hanzoai';
const api = new AgentsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getAgentsSessions();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()cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.AgentsAPI.GetAgentsSessions(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(&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).getAgentsSessions();curl https://api.hanzo.ai/v1/agents/sessions \
-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?