API Reference
Libraries
API Overview
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
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
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.