Skip to content
Agent Graph Agent Graph API
Agent Graph
API Reference
Graphs

Retrieve a graph

client.graphs.retrieve(stringgraphID, GraphRetrieveParams { as_of, ifNoneMatch } params?, RequestOptionsoptions?): Graph { id, as_of_event_id, counts, 6 more }
GET/graphs/{graph_id}

Retrieves a graph: what history it holds (retention) and how its nodes stand (counts), now or as of any retained event.

This is the cheapest overview of a graph: one small object however many nodes it has. Poll it with If-None-Match to learn when anything changes.

ParametersExpand Collapse
graphID: string
params: GraphRetrieveParams { as_of, ifNoneMatch }
as_of?: string | number

Query param: 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.

One of the following:
string
number
ifNoneMatch?: string

Header param: The ETag of a response you have. If nothing has changed, the reply is 304 Not Modified, with no body.

ReturnsExpand Collapse
Graph { 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.

id: string

Unique identifier for the graph, gph_….

as_of_event_id: string

The event this graph’s counts are as of. Pass it as as_of to read other objects at the same moment.

counts: GraphCounts { agents, blocked, by_state, 3 more }

How many nodes the graph has, by kind and state.

agents: number

Nodes of kind agent.

blocked: number

Unfinished nodes waiting on another node.

by_state: ByState { canceled, completed, failed, 3 more }

Nodes in each state.

canceled: number
completed: number
failed: number
idle: number
input_required: number
working: number
nodes: number

Every node.

sessions: number

Nodes of kind session.

stale: number

Nodes that are stale: working, but silent too long.

created: number

When the share was made, in Unix milliseconds.

formatint64
last_event: number

When its most recent event happened, in Unix milliseconds.

formatint64
object: "graph"

String representing the object’s type: always graph.

retention: Retention { 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.

event_count: number

How many events are held.

first_event_created: number | null

When the oldest event happened, in Unix milliseconds.

formatint64
first_event_id: string | null

The oldest event you can read, or ask as_of. null while the graph has no events.

last_event_created: number | null

When the newest event happened, in Unix milliseconds.

formatint64
last_event_id: string | null

The newest event. null while the graph has no events.

source: "watch" | "paste" | "upload"

How the graph was shared. watch is a live share from agent-graph watch-remote; this version of the API returns only those.

One of the following:
"watch"
"paste"
"upload"
url: string

Where to see the graph in the viewer. Only the account that owns it can open it.

formaturi

Retrieve a graph

import AgentGraph from '@chofter/agent-graph-api';

const client = new AgentGraph({
  apiKey: process.env['AGENT_GRAPH_API_KEY'], // This is the default and can be omitted
});

const graph = await client.graphs.retrieve('gph_k3P9xQ2mWt7a');

console.log(graph.id);
{
  "id": "gph_k3P9xQ2mWt7a",
  "object": "graph",
  "as_of_event_id": "evt_01M4G3G4E8Q9R2M5X4T6W8Y0B1",
  "source": "watch",
  "url": "https://agentgraph.chofter.com/l/k3P9xQ2mWt7a",
  "created": 1790959209012,
  "last_event": 1791541907912,
  "retention": {
    "first_event_id": "evt_01M4FXYWR82B8XK0V5QJ7M1N3R",
    "last_event_id": "evt_01M4G3G4E8Q9R2M5X4T6W8Y0B1",
    "first_event_created": 1791536100104,
    "last_event_created": 1791541907912,
    "event_count": 1638
  },
  "counts": {
    "nodes": 214,
    "sessions": 9,
    "agents": 205,
    "stale": 1,
    "blocked": 6,
    "by_state": {
      "working": 7,
      "input_required": 1,
      "idle": 3,
      "completed": 198,
      "failed": 4,
      "canceled": 1
    }
  }
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid limit: must be between 1 and 1000.",
    "param": "limit",
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "expand_too_deep",
    "message": "The path children.children.children.children.children goes 5 levels deep; at most 4 are allowed.",
    "param": "expand",
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "Invalid API key: ag_sk_live_****Xa9T.",
    "param": null,
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
{
  "error": {
    "type": "permission_error",
    "code": "api_key_restricted",
    "message": "This restricted key can't read gph_k3P9xQ2mWt7a.",
    "param": null,
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such node: node_Y2xhdWRlLWNvZGU6NWYyYzFlOWEtOGQxYi00YjZlLTlhNTEtMGY2ZjJjN2QzZTEwL2I4MWMyMmUwOWY3YTNjNTU.",
    "param": "node_id",
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "node_not_yet_created",
    "message": "The node node_Y2xhdWRlLWNvZGU6NWYyYzFlOWEtOGQxYi00YjZlLTlhNTEtMGY2ZjJjN2QzZTEwL2EzZmQwN2MyYjE5ZTRkNjE is created by evt_01M4G2FMPN7KD3N1PZ0QX8RM4A, after as_of.",
    "param": "as_of",
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors",
    "first_event_id": "evt_01M4G2FMPN7KD3N1PZ0QX8RM4A"
  }
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "outside_retention_window",
    "message": "This graph holds events from evt_01M4FXYWR82B8XK0V5QJ7M1N3R to evt_01M4G3G4E8Q9R2M5X4T6W8Y0B1.",
    "param": "as_of",
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors",
    "first_event_id": "evt_01M4FXYWR82B8XK0V5QJ7M1N3R",
    "last_event_id": "evt_01M4G3G4E8Q9R2M5X4T6W8Y0B1"
  }
}
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit",
    "message": "Too many requests. Try again in 1 second.",
    "param": null,
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
{
  "error": {
    "type": "api_error",
    "code": "api_error",
    "message": "Something went wrong. Try again, and include the Request-Id if it keeps happening.",
    "param": null,
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
Returns Examples
{
  "id": "gph_k3P9xQ2mWt7a",
  "object": "graph",
  "as_of_event_id": "evt_01M4G3G4E8Q9R2M5X4T6W8Y0B1",
  "source": "watch",
  "url": "https://agentgraph.chofter.com/l/k3P9xQ2mWt7a",
  "created": 1790959209012,
  "last_event": 1791541907912,
  "retention": {
    "first_event_id": "evt_01M4FXYWR82B8XK0V5QJ7M1N3R",
    "last_event_id": "evt_01M4G3G4E8Q9R2M5X4T6W8Y0B1",
    "first_event_created": 1791536100104,
    "last_event_created": 1791541907912,
    "event_count": 1638
  },
  "counts": {
    "nodes": 214,
    "sessions": 9,
    "agents": 205,
    "stale": 1,
    "blocked": 6,
    "by_state": {
      "working": 7,
      "input_required": 1,
      "idle": 3,
      "completed": 198,
      "failed": 4,
      "canceled": 1
    }
  }
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid limit: must be between 1 and 1000.",
    "param": "limit",
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "expand_too_deep",
    "message": "The path children.children.children.children.children goes 5 levels deep; at most 4 are allowed.",
    "param": "expand",
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "Invalid API key: ag_sk_live_****Xa9T.",
    "param": null,
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
{
  "error": {
    "type": "permission_error",
    "code": "api_key_restricted",
    "message": "This restricted key can't read gph_k3P9xQ2mWt7a.",
    "param": null,
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such node: node_Y2xhdWRlLWNvZGU6NWYyYzFlOWEtOGQxYi00YjZlLTlhNTEtMGY2ZjJjN2QzZTEwL2I4MWMyMmUwOWY3YTNjNTU.",
    "param": "node_id",
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "node_not_yet_created",
    "message": "The node node_Y2xhdWRlLWNvZGU6NWYyYzFlOWEtOGQxYi00YjZlLTlhNTEtMGY2ZjJjN2QzZTEwL2EzZmQwN2MyYjE5ZTRkNjE is created by evt_01M4G2FMPN7KD3N1PZ0QX8RM4A, after as_of.",
    "param": "as_of",
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors",
    "first_event_id": "evt_01M4G2FMPN7KD3N1PZ0QX8RM4A"
  }
}
{
  "error": {
    "type": "invalid_request_error",
    "code": "outside_retention_window",
    "message": "This graph holds events from evt_01M4FXYWR82B8XK0V5QJ7M1N3R to evt_01M4G3G4E8Q9R2M5X4T6W8Y0B1.",
    "param": "as_of",
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors",
    "first_event_id": "evt_01M4FXYWR82B8XK0V5QJ7M1N3R",
    "last_event_id": "evt_01M4G3G4E8Q9R2M5X4T6W8Y0B1"
  }
}
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit",
    "message": "Too many requests. Try again in 1 second.",
    "param": null,
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}
{
  "error": {
    "type": "api_error",
    "code": "api_error",
    "message": "Something went wrong. Try again, and include the Request-Id if it keeps happening.",
    "param": null,
    "doc_url": "https://agentgraph.chofter.com/docs/reference#errors"
  }
}