## List nodes **get** `/graphs/{graph_id}/nodes` Returns a graph's nodes as of a point in its history, filtered and ordered as you ask. Common uses: | To list | Send | | ---------------------------------- | ------------------------------------------- | | The top-level trees | `is_root=true` | | A node's children | `parent_id=node_…` | | Everything under a node | `ancestor_id=node_…&order=tree` | | The top three levels under it | `ancestor_id=node_…&max_depth=3&order=tree` | | Everything waiting on a person | `state=input_required` | | What may have hung | `stale=true` | | What's blocked behind another node | `blocked=true` | Filters combine with AND. In tree order (`order=tree`), each parent comes before its children, and siblings are oldest first, so a page never separates a node from what places it; with a filter, the nodes that match keep that order. ### Path Parameters - `graph_id: string` ### Query Parameters - `agent_type: optional string` Only agents of this type, e.g. `Explore`. - `ancestor_id: optional string` Only nodes under this one, at any depth (not the node itself). - `as_of: optional string or number` Answer as of this point in the graph's history: an event id (`evt_…`, the state just after that event) or a Unix time in milliseconds (the state after the last event at or before it). Leave it out for now. Must be within the graph's `retention`, else `410 outside_retention_window`. To read several pages or objects at one moment, pass the `as_of_event_id` of the first response. - `EventID = string` - `UnixTimeMs = number` - `blocked: optional boolean` Only nodes that are (`true`) or aren't (`false`) waiting on another node. - `created: optional object { gt, gte, lt, lte }` Only nodes that started in this range. - `gt: optional number` After this time. - `gte: optional number` At or after this time. - `lt: optional number` Before this time. - `lte: optional number` At or before this time. - `ending_before: optional string` A cursor: an object id from the list. Returns the page before it. Pass the first `id` of the page you have to get the previous one. - `expand: optional array of string` Fields to expand on each node, with the `data.` prefix: `expand[]=data.parent`, `expand[]=data.blocked.on`. `children` and `descendants` can't be expanded in a list (use `parent_id` or `ancestor_id` instead). Send one `expand[]` per path. A path goes at most 4 levels deep; at most 20 paths per request. An expanded field appears beside its `_id` field, which is always there; one not expanded is absent. - `is_root: optional boolean` Only roots (`true`) or only non-roots (`false`). - `kind: optional NodeKind` Only sessions or only agents. - `"session"` - `"agent"` - `last_event: optional object { gt, gte, lt, lte }` Only nodes whose last event is in this range. - `gt: optional number` After this time. - `gte: optional number` At or after this time. - `lt: optional number` Before this time. - `lte: optional number` At or before this time. - `limit: optional number` How many objects to return, from 1 to 1,000. - `max_depth: optional number` With `ancestor_id`: only nodes at most this many levels below it. 1 is its children. - `order: optional "newest" or "tree"` `newest`: most recently started first. `tree`: depth-first, each parent before its children, siblings oldest first. - `"newest"` - `"tree"` - `parent_id: optional string` Only nodes directly under this one. - `provider: optional string` Only nodes from this agent tool, e.g. `claude-code`. - `root_id: optional string` Only nodes in this tree, the root included. - `session_id: optional string` Only this session and the agents in it. - `stale: optional boolean` Only nodes that are, or aren't, `stale`. - `starting_after: optional string` A cursor: an object id from the list. Returns the page after it. Pass the last `id` of the page you have to get the next one. - `state: optional array of NodeState` Only nodes in these states. Send one `state[]` per state. - `"working"` - `"input_required"` - `"idle"` - `"completed"` - `"failed"` - `"canceled"` ### Header Parameters - `"If-None-Match": optional string` ### Returns - `as_of_event_id: string` The event the list is as of. Keep it as `as_of` for every page. - `data: array of Node` - `id: string` Unique identifier for the node within its graph: `node_` and the base64url of `provider_ref`. - `agent_type: string` For an agent, its type, as the tool names it (`Explore`, `general-purpose`, …). - `as_of_event_id: string` The event this node is shown as of. - `attention: string` While `input_required`: what the person is being asked. Untrusted text. - `background: boolean` Whether it was started in the background, so its requester carries on without waiting. `null` when unknown. - `background_agent_count: number` 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. - `blocked: Blocked` What stands between a node and carrying on. - `child_count: number` How many nodes sit directly under it. - `created: number` When it started (or was first seen), in Unix milliseconds. - `cwd: string` The directory it runs in, when reported. - `depth: number` How far below its root it is: 0 for a root. - `descendant_count: number` How many nodes sit under it, at any depth: the size of `descendants`. - `ended: number` When it finished, in Unix milliseconds. `null` while it hasn't. - `graph_id: string` The graph it belongs to. - `headline: string` One line on what it's doing now: `summary`, else the task in progress. Untrusted text. - `kind: NodeKind` `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"` - `"agent"` - `last_event: number` When it last had an event, in Unix milliseconds. - `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). - `"env"` - `"run"` - `"process"` - `"suggested"` - `object: "node"` String representing the object's type: always `node`. - `"node"` - `parent_id: string` The node it sits under: the agent or session that started it. `null` for a root. - `provider: string` The agent tool: `claude-code`, `codex`, `cursor`, or another that reports to Agent Graph. - `provider_ref: string` The id the agent tool gave it: `:` for a session, `:/` for an agent. Not an id in this API: use it to match the node to the tool's own records. - `purpose: string` Why it was started, from the request that started it. Untrusted text. - `requested_by_id: string` 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. - `root_id: string` 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`. - `session_id: string` The session it runs in: itself, for a session; for an agent, the nearest session above it. - `spawn_call_id: string` The tool call, in its requester's session, that started it: matches a `spawns[].call_id` on `requested_by`. - `stale: boolean` `working`, waiting on nothing, and silent for 30 minutes: it may have hung or crashed. Measured against `as_of`, not now. - `state: NodeState` 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. - `"working"` - `"input_required"` - `"idle"` - `"completed"` - `"failed"` - `"canceled"` - `summary: string` Its own latest status line, if it reports one. Untrusted text. - `task_counts: TaskCounts` Its tasks, by status. - `completed: number` - `in_progress: number` - `open: number` Not completed: `pending` and `in_progress`. - `pending: number` - `total: number` - `title: string` The session's name, as its tool shows it. It can change. Untrusted text. - `children: optional unknown` The nodes directly under it, oldest first: the first 100, and a `url` for the rest. Present only when expanded. - `descendants: optional unknown` 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. - `messages: optional array of Message` Messages it has sent and received, oldest first. Present only when expanded. - `id: string` The tool's id for the message. - `body: string` The whole message, only if the share was made with body capture on. Untrusted text. - `created: number` When it was sent, in Unix milliseconds. - `direction: "sent" or "received"` - `"sent"` - `"received"` - `peer_id: string` The node on the other side, when it's one in this graph. - `peer_name: string` The tool's name for the other side, when it isn't a node in this graph. - `reply_to_message_id: string` The message it answers. - `summary: string` Untrusted text. - `parent: optional Node` The parent node. Present only when expanded. - `requested_by: optional Node` The node that requested it. Present only when expanded. - `root: optional Node` The root node. Present only when expanded. - `session: optional Node` The session node. Present only when expanded. - `spawns: optional array of Spawn` The children it has asked for, oldest first. Present only when expanded. - `agent_type: string` - `background: boolean` If false, the requester is blocked until the call returns. - `call_id: string` The tool call that asked for it. - `child_id: string` The node it started, once matched. Before the call returns this can be a best guess, corrected when it does. - `kind: "agent" or "session"` `agent`: an agent in the same session. `session`: a separate session, e.g. `codex exec` run from a shell. - `"agent"` - `"session"` - `purpose: string` Untrusted text. - `requested: number` When it was asked for, in Unix milliseconds. - `returned: boolean` Whether the call has returned. - `run: boolean` Whether it's through `agent-graph run`, when known. - `title: string` For a session, the name it was to be given. - `tasks: optional array of Task` Its task list, in the tool's order. Present only when expanded. - `id: string` The tool's id for the task, unique within the node. - `active_text: string` How the tool words it while it's in progress (`Running the tests`). Untrusted text. - `status: "pending" or "in_progress" or "completed"` - `"pending"` - `"in_progress"` - `"completed"` - `text: string` What the task is. Untrusted text. - `waits: optional array of Wait` What it has waited on and is waiting on, oldest first. Present only when expanded. - `id: string` The wait's id, unique within the node. - `ended: number` When it stopped, in Unix milliseconds. - `kind: "spawn" or "explicit"` `spawn`: waiting for a child it asked for, until the call returns. `explicit`: any other wait the tool reported. - `"spawn"` - `"explicit"` - `on_id: string` The node waited on. `null` while a requested child hasn't started. - `open: boolean` Whether it's still waiting. - `reason: string` Untrusted text. - `started: number` When it started waiting, in Unix milliseconds. - `has_more: boolean` Whether there are more after this page. - `object: "list"` - `"list"` - `url: string` The URL for this list, with every parameter that defined it (including `as_of`). Add `starting_after` to get the next page. ### Example ```http curl https://agentgraph.chofter.com/api/v1/graphs/$GRAPH_ID/nodes \ -H "Authorization: Bearer $AGENT_GRAPH_API_KEY" ``` #### Response ```json { "object": "list", "url": "/api/v1/graphs/gph_k3P9xQ2mWt7a/nodes?parent_id=node_Y2xhdWRlLWNvZGU6NWYyYzFlOWEtOGQxYi00YjZlLTlhNTEtMGY2ZjJjN2QzZTEw&as_of=evt_01M4G3G4E8Q9R2M5X4T6W8Y0B1", "as_of_event_id": "evt_01M4G3G4E8Q9R2M5X4T6W8Y0B1", "has_more": true, "data": [ { "id": "node_Y2xhdWRlLWNvZGU6NWYyYzFlOWEtOGQxYi00YjZlLTlhNTEtMGY2ZjJjN2QzZTEwL2EzZmQwN2MyYjE5ZTRkNjE", "object": "node", "as_of_event_id": "evt_01M4G3G4E8Q9R2M5X4T6W8Y0B1", "graph_id": "gph_k3P9xQ2mWt7a", "provider_ref": "claude-code:5f2c1e9a-8d1b-4b6e-9a51-0f6f2c7d3e10/a3fd07c2b19e4d61", "provider": "claude-code", "kind": "agent", "parent_id": "node_Y2xhdWRlLWNvZGU6NWYyYzFlOWEtOGQxYi00YjZlLTlhNTEtMGY2ZjJjN2QzZTEw", "root_id": "node_Y2xhdWRlLWNvZGU6NWYyYzFlOWEtOGQxYi00YjZlLTlhNTEtMGY2ZjJjN2QzZTEw", "session_id": "node_Y2xhdWRlLWNvZGU6NWYyYzFlOWEtOGQxYi00YjZlLTlhNTEtMGY2ZjJjN2QzZTEw", "requested_by_id": "node_Y2xhdWRlLWNvZGU6NWYyYzFlOWEtOGQxYi00YjZlLTlhNTEtMGY2ZjJjN2QzZTEw", "depth": 1, "state": "working", "stale": false, "attention": null, "title": null, "summary": "Reading the auth middleware", "headline": "Reading the auth middleware", "purpose": "Find every caller of the old session store", "agent_type": "Explore", "background": false, "link_method": null, "spawn_call_id": "toolu_01HxV9qT3mJb7d2KcL5nRw8E", "cwd": "/Users/dev/work/api", "created": 1791540843221, "ended": null, "last_event": 1791541903812, "child_count": 1, "descendant_count": 1, "background_agent_count": 0, "task_counts": { "total": 4, "pending": 1, "in_progress": 1, "completed": 2, "open": 2 }, "blocked": { "on_ids": [ "node_Y2xhdWRlLWNvZGU6NWYyYzFlOWEtOGQxYi00YjZlLTlhNTEtMGY2ZjJjN2QzZTEwL2I4MWMyMmUwOWY3YTNjNTU" ], "starting": 0, "node_count": 1, "open_tasks": 5, "cycle": false } } ] } ```