> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitecircle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a Run Graph

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

```bash theme={null}
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 team. Pass `environment_id` on every request. Runs with the same `run_id` in other Environments are never included.

```json theme={null}
{
  "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](/latest/events/get-event) endpoint to retrieve moderation details.


## OpenAPI

````yaml GET /api/runs/{run_id}/graph
openapi: 3.1.0
info:
  title: WhiteCircle API Backend
  description: 'Authentication: Bearer API Key Required'
  license:
    name: ''
  version: '2026-06-01'
servers:
  - url: https://eu.whitecircle.com
  - url: https://us.whitecircle.com
security: []
tags:
  - name: Session
    description: Session-based content checking and moderation
  - name: User
    description: User risk assessment and scoring
  - name: Policy
    description: Policy management CRUD
  - name: Metric
    description: Metric management CRUD
  - name: Artifact
    description: Standalone artifact moderation
  - name: Events
    description: Append-only event ingestion and public event lookup
  - name: Condition
    description: Metadata-driven policy routing
paths:
  /api/runs/{run_id}/graph:
    get:
      tags:
        - Events
      operationId: get_public_run_graph
      parameters:
        - name: whitecircle-version
          in: header
          description: API Version
          required: true
          schema:
            type: string
          example: '2026-06-01'
        - name: run_id
          in: path
          required: true
          schema:
            type: string
        - name: environment_id
          in: query
          description: Required environment selector.
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: Number of Events to return. Values above 100 are clamped to 100.
          required: false
          schema:
            type: integer
            format: int32
            default: 100
            minimum: 1
        - name: after
          in: query
          required: false
          schema:
            type:
              - string
              - 'null'
      responses:
        '200':
          description: Run graph retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventGraphResponse'
        '400':
          description: Invalid run or cursor
        '500':
          description: Internal server error
      security:
        - bearerAuth: []
components:
  schemas:
    EventGraphResponse:
      type: object
      required:
        - nodes
        - edges
        - has_more
      properties:
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/EventGraphNode'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/EventGraphEdge'
        next_cursor:
          type:
            - string
            - 'null'
        has_more:
          type: boolean
      example:
        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
    EventGraphNode:
      type: object
      required:
        - run_id
        - event_id
        - environment_id
        - type
      properties:
        run_id:
          type: string
        event_id:
          type: string
        internal_event_id:
          type:
            - string
            - 'null'
        environment_id:
          type: string
        type:
          type: string
        name:
          type:
            - string
            - 'null'
        content_field:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/EventContentField'
        call_id:
          type:
            - string
            - 'null'
        stream_id:
          type:
            - string
            - 'null'
        sequence:
          type:
            - integer
            - 'null'
          format: int64
        role:
          type:
            - string
            - 'null'
        status:
          type:
            - string
            - 'null'
        violation:
          type:
            - boolean
            - 'null'
        effective_violation:
          type:
            - boolean
            - 'null'
        not_sure:
          type:
            - boolean
            - 'null'
        created_at:
          type:
            - string
            - 'null'
        updated_at:
          type:
            - string
            - 'null'
        external_session_id:
          type:
            - string
            - 'null'
    EventGraphEdge:
      type: object
      required:
        - kind
        - source
        - target
      properties:
        kind:
          $ref: '#/components/schemas/EventGraphEdgeKind'
        source:
          $ref: '#/components/schemas/EventGraphNodeRef'
        target:
          $ref: '#/components/schemas/EventGraphNodeRef'
    EventContentField:
      type: string
      enum:
        - content
        - delta
        - arguments
        - output
        - definition
        - input
        - instructions
        - state
    EventGraphEdgeKind:
      type: string
      enum:
        - parent
        - link
    EventGraphNodeRef:
      type: object
      required:
        - run_id
        - event_id
      properties:
        run_id:
          type: string
        event_id:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API Key required. Format: Bearer wc-your-api-key'

````