# Get a Run Graph

`GET /api/runs/{run_id}/graph`

Base URLs: `https://eu.whitecircle.com`, `https://us.whitecircle.com`

OpenAPI: [latest/openapi.json](https://whitecircle.com/docs/latest/openapi.json)

Retrieve the latest Event node for each `event_id` in a Run, together with structural parent edges and causal links.

```bash
curl "https://eu.whitecircle.com/api/runs/run_main/graph?environment_id=environment_123&limit=100" \
  -H "Authorization: Bearer wc-your-api-key" \
  -H "whitecircle-version: 2026-06-01"
```

The API key determines the workspace. Pass `environment_id` on every request. Runs with the same `run_id` in other Environments are never included.

```json
{
  "nodes": [
    {
      "type": "message",
      "content_field": "content",
      "status": "completed",
      "run_id": "run_main",
      "event_id": "final_answer",
      "internal_event_id": "019...",
      "environment_id": "environment_1"
    },
    {
      "type": "tool",
      "content_field": "output",
      "status": "completed",
      "run_id": "run_security",
      "event_id": "security_output",
      "internal_event_id": "019...",
      "environment_id": "environment_1"
    }
  ],
  "edges": [
    {
      "kind": "link",
      "source": { "run_id": "run_main", "event_id": "final_answer" },
      "target": { "run_id": "run_security", "event_id": "security_output" }
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

## Edges and unresolved targets

Every edge connects a `source` Event to a `target` Event.

* `parent` connects an Event to its single structural parent. Run trees and breadcrumbs use only parent edges.
* `link` records a causal input and may point to another run in the same Environment.

The response includes every edge target in `nodes`, including targets outside the requested page or in another Run in the same Environment. If the target Event has not been stored yet, its node contains the requested public IDs and `internal_event_id: null`. This preserves the reference without pretending the target exists.

## Pagination

`limit` defaults to 100. The API rejects `0` and clamps any value above 100 to 100. Pass `next_cursor` as `after` to load the next page. A cursor is valid only for the Environment and Run that produced it; using it with another scope returns `400`.

The graph returns the latest attempt for each public `event_id`, regardless of whether it completed or failed. A retry created while you paginate moves that Event to its new latest-attempt position, which may be before your current cursor. Restart pagination when you need a fresh complete latest-attempt view; cursors do not snapshot a changing Run.

Use the returned `internal_event_id` with the [Get Event](https://whitecircle.com/docs/latest/events/get-event.md) endpoint to retrieve moderation details.

## Authorizations

- `Authorization` (`string`, header, required): API Key required. Format: Bearer wc-your-api-key.

## Headers

- `whitecircle-version` (`string`, required): API Version. Example: `"2026-06-01"`.

## Path Parameters

- `run_id` (`string`, required): Run to load.

## Query Parameters

- `environment_id` (`string`, required): Required environment selector.
- `limit` (`integer<int32>`, optional, default: `100`): Number of Events to return. Values above 100 are clamped to 100. Required range: `x >= 1`.
- `after` (`string | null`, optional): `next_cursor` from the previous page. Valid only for the same Environment and run.

## Request example

```bash
curl --request GET \
  --url 'https://eu.whitecircle.com/api/runs/<run_id>/graph?environment_id=<environment_id>&limit=100' \
  --header "Authorization: Bearer $WHITECIRCLE_API_KEY" \
  --header 'whitecircle-version: 2026-06-01'
```

## Response

### 200

Run graph retrieved

`application/json`

One page of a run graph: the latest attempt of each Event plus parent and link edges.

- `nodes` (`object[]`, required): Events in this page, plus every edge target, including targets in other runs or not stored yet.
- `nodes.run_id` (`string`, required): Run of the Event.
- `nodes.event_id` (`string`, required): Your ID for the Event.
- `nodes.environment_id` (`string`, required): Environment of the Event.
- `nodes.type` (`string`, required): Kind of Event, or `unknown` for a target that has not been stored yet.
- `nodes.internal_event_id` (`string | null`, optional): White Circle's ID for the latest attempt. `null` when the Event has not been stored yet.
- `nodes.name` (`string | null`, optional): Tool, function, agent, or artifact name sent with the Event.
- `nodes.content_field` (`null | enum<string>`, optional): Content field the Event was checked on. Available options: `content`, `delta`, `arguments`, `output`, `definition`, `input`, `instructions`, `state`.
- `nodes.call_id` (`string | null`, optional): Tool or function invocation ID sent with the Event.
- `nodes.stream_id` (`string | null`, optional): Stream ID sent with the Event.
- `nodes.sequence` (`integer<int64> | null`, optional): Stream position sent with the Event.
- `nodes.role` (`string | null`, optional): Role the Event was checked with.
- `nodes.status` (`string | null`, optional): Outcome of the latest attempt.
- `nodes.violation` (`boolean | null`, optional): Whether the initial check flagged the Event.
- `nodes.effective_violation` (`boolean | null`, optional): Final verdict after White Circle's secondary review. Prefer it over `violation`.
- `nodes.not_sure` (`boolean | null`, optional): `true` when the check could not reach a confident verdict.
- `nodes.created_at` (`string | null`, optional): When the latest attempt was saved. ISO 8601 timestamp.
- `nodes.updated_at` (`string | null`, optional): When the latest attempt last changed. ISO 8601 timestamp.
- `nodes.external_session_id` (`string | null`, optional): Session the Event belongs to.
- `edges` (`object[]`, required): Parent and link relationships declared by Events in this page.
- `edges.kind` (`enum<string>`, required): Relationship type. Available options: `parent`, `link`.
- `edges.source` (`object`, required): The Event that declared the relationship.
- `edges.source.run_id` (`string`, required): Run of the referenced Event.
- `edges.source.event_id` (`string`, required): `event_id` of the referenced Event.
- `edges.target` (`object`, required): The parent or linked Event.
- `edges.target.run_id` (`string`, required): Run of the referenced Event.
- `edges.target.event_id` (`string`, required): `event_id` of the referenced Event.
- `has_more` (`boolean`, required): `true` if more Events remain after this page.
- `next_cursor` (`string | null`, optional): Pass as `after` to load the next page. `null` on the last page.

**Example**

```json
{
  "edges": [
    {
      "kind": "parent",
      "source": {
        "event_id": "evt_user_001",
        "run_id": "run_refund_123"
      },
      "target": {
        "event_id": "evt_tool_output_001",
        "run_id": "run_refund_123"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "nodes": [
    {
      "content_field": "content",
      "created_at": "2026-06-01T12:00:00Z",
      "environment_id": "5d1e6f70-6f31-4c1e-9a2b-1f4d0d4c9a10",
      "event_id": "evt_user_001",
      "internal_event_id": "11111111-1111-4111-8111-111111111111",
      "role": "user",
      "run_id": "run_refund_123",
      "status": "completed",
      "type": "message",
      "violation": false
    },
    {
      "content_field": "output",
      "created_at": "2026-06-01T12:00:01Z",
      "environment_id": "5d1e6f70-6f31-4c1e-9a2b-1f4d0d4c9a10",
      "event_id": "evt_tool_output_001",
      "internal_event_id": "22222222-2222-4222-8222-222222222222",
      "name": "lookup_order",
      "run_id": "run_refund_123",
      "status": "completed",
      "type": "tool",
      "violation": false
    }
  ]
}
```

### 400

Invalid run or cursor

### 500

Internal server error
