Graphs
A graph is one of your account’s live shares: the sessions and agents agent-graph watch-remote streams from a machine, kept on the site while it’s in use, and deleted after a week with no new events.
Retrieve a graph to see what it holds (retention), how big it is, and how its nodes stand (counts), now or as of any retained event.
List graphs
Retrieve a graph
ModelsExpand Collapse
Graph object { id, as_of_event_id, counts, 6 more } One of your account’s live shares, and how its nodes stand at as_of_event_id.
One of your account’s live shares, and how its nodes stand at as_of_event_id.
The event this graph’s counts are as of. Pass it as as_of to read other objects at the same moment.
How many nodes the graph has, by kind and state.
How many nodes the graph has, by kind and state.
The span of history the site holds for this graph now, and so the range as_of can take. A live share keeps between 1,000 and 2,000 events, trimmed from the start as new ones arrive.
The span of history the site holds for this graph now, and so the range as_of can take. A live share keeps between 1,000 and 2,000 events, trimmed from the start as new ones arrive.
Retention object { event_count, first_event_created, first_event_id, 2 more } The span of history the site holds for this graph now, and so the range as_of can take. A live share keeps between 1,000 and 2,000 events, trimmed from the start as new ones arrive.
The span of history the site holds for this graph now, and so the range as_of can take. A live share keeps between 1,000 and 2,000 events, trimmed from the start as new ones arrive.
GraphsNodes
A node is a session (one run of a coding agent) or an agent it started. Nodes form trees:
session claude-code:5f2c1e… depth 0, parent_id null
├─ agent claude-code:5f2c1e…/a3fd07… depth 1
│ └─ agent claude-code:5f2c1e…/b81c22… depth 2
└─ agent claude-code:5f2c1e…/c90d13… depth 1Every node says where it sits: parent_id, root_id (the top of its tree, following sessions that started other sessions), session_id (the session it runs in) and depth.
State. A node’s state is one of:
| State | Meaning |
|---|---|
working | Doing something. |
input_required | Waiting on a person: a permission prompt, a question, a plan to approve. attention says what’s asked. |
idle | A session whose turn is over, alive and waiting for its next prompt. |
completed | Finished. |
failed | Finished with an error. |
canceled | Stopped before it finished. |
Waiting on another node isn’t a state: a node can be working and blocked at once. blocked says what it’s waiting on, directly (on_ids) and in all (how many nodes, how many open tasks among them), and whether the waits form a cycle that can never finish. A working node with no events for 30 minutes, and nothing it’s waiting on, is stale: it may have hung or crashed.
List nodes
Search nodes
Retrieve a node
ModelsExpand Collapse
Node object { id, agent_type, as_of_event_id, 39 more } A session or an agent, as it stood at as_of_event_id.
Fields ending _id or _ids are always present, as ids. The fields beside them without that ending (parent, root, …), and children, descendants, tasks, spawns, waits and messages, appear only when expanded.
A session or an agent, as it stood at as_of_event_id.
Fields ending _id or _ids are always present, as ids. The fields beside them without that ending (parent, root, …), and children, descendants, tasks, spawns, waits and messages, appear only when expanded.
Whether it was started in the background, so its requester carries on without waiting. null when unknown.
Helpers its tool ran on its own between turns (memory extraction, summaries, prompt suggestions). They report nothing about what they’re for, so they’re counted, not made nodes.
One line on what it’s doing now: summary, else the task in progress. Untrusted text.
session: one run of a coding agent (Claude Code, Codex, Cursor, …). agent: an agent started inside a session, by it or by another agent.
session: one run of a coding agent (Claude Code, Codex, Cursor, …). agent: an agent started inside a session, by it or by another agent.
link_method: "env" or "run" or "process" or "suggested"For a session started by another, how that was worked out: env (it inherited its parent’s identity), run (agent-graph run started it), process (its parent’s agent is among its processes) or suggested (it took a name its parent suggested).
For a session started by another, how that was worked out: env (it inherited its parent’s identity), run (agent-graph run started it), process (its parent’s agent is among its processes) or suggested (it took a name its parent suggested).
The id the agent tool gave it: <provider>:<session> for a session, <provider>:<session>/<agent> for an agent. Not an id in this API: use it to match the node to the tool’s own records.
The node whose spawn request started it, when known. Usually the parent; null for a session nothing started, or an agent no request was matched to.
The top of its tree: follow parent_id until it’s null. A session started by another session is in that session’s tree. A root’s root_id is its own id.
The session it runs in: itself, for a session; for an agent, the nearest session above it.
The tool call, in its requester’s session, that started it: matches a spawns[].call_id on requested_by.
working, waiting on nothing, and silent for 30 minutes: it may have hung or crashed. Measured against as_of, not now.
What a node is doing.
working: doing something.input_required: waiting on a person (attention says what for).idle: a session between turns, waiting for its next prompt.completed, failed, canceled: finished.
What a node is doing.
working: doing something.input_required: waiting on a person (attentionsays what for).idle: a session between turns, waiting for its next prompt.completed,failed,canceled: finished.
The nodes directly under it, oldest first: the first 100, and a url for the rest. Present only when expanded.
Every node under it, at any depth, as one flat list in tree order: each parent before its children, siblings oldest first. The first 1,000, and a url for the rest. Present only when expanded.
The children it has asked for, oldest first. Present only when expanded.
The children it has asked for, oldest first. Present only when expanded.
Its task list, in the tool’s order. Present only when expanded.
Its task list, in the tool’s order. Present only when expanded.
Spawn object { agent_type, background, call_id, 7 more } A child a node asked for.
A child a node asked for.
GraphsEvents
An event is one thing that happened in a graph. Events are immutable and ordered by id, which sorts by time.
Each event has the payload its agent tool reported, and changes: every node the event changed, and for each, the fields that changed, from what to what. A node’s derived fields count too: an agent being spawned changes its parent’s child_count, and every ancestor’s descendant_count.
List events starting_after the last one you saw to follow a graph cheaply, or with order=asc from any point to replay its history.
Event types
| Type | payload | When |
|---|---|---|
session.started | cwd?, source? (startup, resume, …), title?, link_method? | A session starts or resumes. |
session.ended | reason? | A session exits. |
agent.spawned | agent_type?, purpose?, background? | An agent starts. |
agent.finished | status (completed, failed, canceled), summary? | An agent stops. |
status | state, summary?, title? | A node’s state or status line changes. |
tasks.updated | items: [{id, text, active_text?, status}] | A to-do tool sent its whole list, which replaces the node’s. |
task.upserted | id, text?, active_text?, status? | One task was created or changed. |
task.deleted | id | A task was removed. |
spawn.requested | call_id, kind (agent, session), agent_type?, purpose?, background | A node asked for a child to start. Unless background, it’s blocked until the call returns. |
spawn.returned | call_id, child?, outcome? | That call returned. |
wait.started | wait_id, on (a provider node id), reason? | A node blocked on another for some other reason. |
wait.ended | wait_id, outcome? | That block cleared. |
message.sent | message_id, to, reply_to?, summary?, body? | One node sent another a message. |
activity | tool, label? | A tool call, when the share records them. |
Ids inside payload are the provider’s own (as in provider_ref), exactly as the agent tool reported them; use node_id and changes for API ids. More types may be added: ignore those you don’t recognise.
List events
Retrieve an event
ModelsExpand Collapse
Event object { id, changes, created, 7 more } One thing that happened in a graph, and every change it made to its nodes.
One thing that happened in a graph, and every change it made to its nodes.
Every node this event changed, starting with node_id. Empty when it changed nothing (a repeated status, say).
Every node this event changed, starting with node_id. Empty when it changed nothing (a repeated status, say).
Each node field that changed, by name, from what to what. Derived fields count (child_count, descendant_count, blocked, headline, task_counts). stale doesn’t, as it changes with time rather than events, and nor do expandable fields.
Each node field that changed, by name, from what to what. Derived fields count (child_count, descendant_count, blocked, headline, task_counts). stale doesn’t, as it changes with time rather than events, and nor do expandable fields.
What the agent tool reported, by type: see event types. Ids in it are the provider’s own. Text in it is untrusted.
type: "session.started" or "session.ended" or "agent.spawned" or 11 moreWhat happened. See event types. More may be added: ignore those you don’t recognise.
What happened. See event types. More may be added: ignore those you don’t recognise.
That node, as it stood just after this event. Present only when expanded.
That node, as it stood just after this event. Present only when expanded.
Whether it was started in the background, so its requester carries on without waiting. null when unknown.
Helpers its tool ran on its own between turns (memory extraction, summaries, prompt suggestions). They report nothing about what they’re for, so they’re counted, not made nodes.
One line on what it’s doing now: summary, else the task in progress. Untrusted text.
session: one run of a coding agent (Claude Code, Codex, Cursor, …). agent: an agent started inside a session, by it or by another agent.
session: one run of a coding agent (Claude Code, Codex, Cursor, …). agent: an agent started inside a session, by it or by another agent.
link_method: "env" or "run" or "process" or "suggested"For a session started by another, how that was worked out: env (it inherited its parent’s identity), run (agent-graph run started it), process (its parent’s agent is among its processes) or suggested (it took a name its parent suggested).
For a session started by another, how that was worked out: env (it inherited its parent’s identity), run (agent-graph run started it), process (its parent’s agent is among its processes) or suggested (it took a name its parent suggested).
The id the agent tool gave it: <provider>:<session> for a session, <provider>:<session>/<agent> for an agent. Not an id in this API: use it to match the node to the tool’s own records.
The node whose spawn request started it, when known. Usually the parent; null for a session nothing started, or an agent no request was matched to.
The top of its tree: follow parent_id until it’s null. A session started by another session is in that session’s tree. A root’s root_id is its own id.
The session it runs in: itself, for a session; for an agent, the nearest session above it.
The tool call, in its requester’s session, that started it: matches a spawns[].call_id on requested_by.
working, waiting on nothing, and silent for 30 minutes: it may have hung or crashed. Measured against as_of, not now.
What a node is doing.
working: doing something.input_required: waiting on a person (attention says what for).idle: a session between turns, waiting for its next prompt.completed, failed, canceled: finished.
What a node is doing.
working: doing something.input_required: waiting on a person (attentionsays what for).idle: a session between turns, waiting for its next prompt.completed,failed,canceled: finished.
The nodes directly under it, oldest first: the first 100, and a url for the rest. Present only when expanded.
Every node under it, at any depth, as one flat list in tree order: each parent before its children, siblings oldest first. The first 1,000, and a url for the rest. Present only when expanded.
The children it has asked for, oldest first. Present only when expanded.
The children it has asked for, oldest first. Present only when expanded.
Its task list, in the tool’s order. Present only when expanded.
Its task list, in the tool’s order. Present only when expanded.
NodeChange object { created, fields, node_id } How one event changed one node.
How one event changed one node.
Each node field that changed, by name, from what to what. Derived fields count (child_count, descendant_count, blocked, headline, task_counts). stale doesn’t, as it changes with time rather than events, and nor do expandable fields.
Each node field that changed, by name, from what to what. Derived fields count (child_count, descendant_count, blocked, headline, task_counts). stale doesn’t, as it changes with time rather than events, and nor do expandable fields.