Events

Get a Run Graph

GET
/api/runs/{run_id}/graph

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

cURL

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 endpoint to retrieve moderation details.

Authorizations

  • Authorizationstringheaderrequired

    API Key required. Format: Bearer wc-your-api-key

Headers

  • whitecircle-versionstringrequired

    API Version

    Example: "2026-06-01"

Path Parameters

  • run_idstringrequired

    Run to load.

Query Parameters

  • environment_idstringrequired

    Required environment selector.

  • limitinteger<int32>default: 100

    Number of Events to return. Values above 100 are clamped to 100.

    Required range: x >= 1

  • afterstring | null

    next_cursor from the previous page. Valid only for the same Environment and run.

Response

application/json

Run graph retrieved

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

  • nodesobject[]required

    Events in this page, plus every edge target, including targets in other runs or not stored yet.

    Show child attributes
    • nodes.run_idstringrequired

      Run of the Event.

    • nodes.event_idstringrequired

      Your ID for the Event.

    • nodes.environment_idstringrequired

      Environment of the Event.

    • nodes.typestringrequired

      Kind of Event, or unknown for a target that has not been stored yet.

    • nodes.internal_event_idstring | null

      White Circle's ID for the latest attempt. null when the Event has not been stored yet.

    • nodes.namestring | null

      Tool, function, agent, or artifact name sent with the Event.

    • nodes.content_fieldnull | enum<string>

      Content field the Event was checked on.

      Available options: content, delta, arguments, output, definition, input, instructions, state

    • nodes.call_idstring | null

      Tool or function invocation ID sent with the Event.

    • nodes.stream_idstring | null

      Stream ID sent with the Event.

    • nodes.sequenceinteger<int64> | null

      Stream position sent with the Event.

    • nodes.rolestring | null

      Role the Event was checked with.

    • nodes.statusstring | null

      Outcome of the latest attempt.

    • nodes.violationboolean | null

      Whether the initial check flagged the Event.

    • nodes.effective_violationboolean | null

      Final verdict after White Circle's secondary review. Prefer it over violation.

    • nodes.not_sureboolean | null

      true when the check could not reach a confident verdict.

    • nodes.created_atstring | null

      When the latest attempt was saved. ISO 8601 timestamp.

    • nodes.updated_atstring | null

      When the latest attempt last changed. ISO 8601 timestamp.

    • nodes.external_session_idstring | null

      Session the Event belongs to.

  • edgesobject[]required

    Parent and link relationships declared by Events in this page.

    Show child attributes
    • edges.kindenum<string>required

      Relationship type.

      Available options: parent, link

    • edges.sourceobjectrequired

      The Event that declared the relationship.

      Show child attributes
      • edges.source.run_idstringrequired

        Run of the referenced Event.

      • edges.source.event_idstringrequired

        event_id of the referenced Event.

    • edges.targetobjectrequired

      The parent or linked Event.

      Show child attributes
      • edges.target.run_idstringrequired

        Run of the referenced Event.

      • edges.target.event_idstringrequired

        event_id of the referenced Event.

  • has_morebooleanrequired

    true if more Events remain after this page.

  • next_cursorstring | null

    Pass as after to load the next page. null on the last page.