## Retrieve a graph

**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.

### Path Parameters

- `graph_id: string`

### Query Parameters

- `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`

### Header Parameters

- `"If-None-Match": optional string`

### Returns

- `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`.

  - `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`

    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.

  - `last_event: number`

    When its most recent event happened, in Unix milliseconds.

  - `object: "graph"`

    String representing the object's type: always `graph`.

    - `"graph"`

  - `retention: Retention`

    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.

    - `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.

    - `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.

    - `"watch"`

    - `"paste"`

    - `"upload"`

  - `url: string`

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

### Example

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

#### Response

```json
{
  "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
    }
  }
}
```