## 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 Parameters

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

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

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

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

### Returns

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

- `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 \
    -H "Authorization: Bearer $AGENT_GRAPH_API_KEY"
```

#### Response

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