List graphs

GET/graphs

Returns the graphs this key can read: your account’s live shares, most recently active first.

Each graph’s counts are as of its own latest event.

Query ParametersExpand Collapse

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.

last_event: optional object { gt, gte, lt, lte }

Only graphs whose latest event is in this range. last_event[gte]=<5 minutes ago> lists the shares active now.

gt: optional number

After this time.

formatint64

gte: optional number

At or after this time.

formatint64

lt: optional number

Before this time.

formatint64

lte: optional number

At or before this time.

formatint64

limit: optional number

How many objects to return, from 1 to 1,000.

minimum1

maximum1000

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.

Header ParametersExpand Collapse

"If-None-Match": optional string

ReturnsExpand Collapse

as_of_event_id: string

Always null: each graph has its own history, so each graph carries its own as_of_event_id.

data: array of Graph { id, as_of_event_id, counts, 6 more }

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: object { 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

When the oldest event happened, in Unix milliseconds.

formatint64

first_event_id: string

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

last_event_created: number

When the newest event happened, in Unix milliseconds.

formatint64

last_event_id: string

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

source: "watch" or "paste" or "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

has_more: boolean

Whether there are more after this page.

object: "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.

List graphs

curl https://agentgraph.chofter.com/api/v1/graphs \
    -H "Authorization: Bearer $AGENT_GRAPH_API_KEY"

{
  "object": "list",
  "url": "/api/v1/graphs",
  "as_of_event_id": null,
  "has_more": false,
  "data": [
    {
      "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": "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

{
  "object": "list",
  "url": "/api/v1/graphs",
  "as_of_event_id": null,
  "has_more": false,
  "data": [
    {
      "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": "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"
  }
}