Get a Run Graph

GET

api

runs

{run_id}

graph

cURL

curl --request GET \
  --url https://eu.whitecircle.com/api/runs/{run_id}/graph \
  --header 'Authorization: Bearer <token>' \
  --header 'whitecircle-version: <whitecircle-version>'

import requests

url = "https://eu.whitecircle.com/api/runs/{run_id}/graph"

headers = {
    "whitecircle-version": "<whitecircle-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'whitecircle-version': '<whitecircle-version>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://eu.whitecircle.com/api/runs/{run_id}/graph', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://eu.whitecircle.com/api/runs/{run_id}/graph",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "whitecircle-version: <whitecircle-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://eu.whitecircle.com/api/runs/{run_id}/graph"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("whitecircle-version", "<whitecircle-version>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://eu.whitecircle.com/api/runs/{run_id}/graph")
  .header("whitecircle-version", "<whitecircle-version>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://eu.whitecircle.com/api/runs/{run_id}/graph")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["whitecircle-version"] = '<whitecircle-version>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

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

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.

{
  "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

Authorization

string

header

required

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

Headers

whitecircle-version

string

required

API Version

Path Parameters

run_id

string

required

Query Parameters

environment_id

string

required

Required environment selector.

limit

integer<int32>

default:100

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

Required range: x >= 1

after

string | null

Response

Run graph retrieved

nodes

object[]

required

Hide child attributes

nodes.run_id

string

required

nodes.event_id

string

required

nodes.environment_id

string

required

nodes.type

string

required

nodes.internal_event_id

string | null

nodes.name

string | null

nodes.content_field

null | enum<string>

Available options:

content,

delta,

arguments,

output,

definition,

input,

instructions,

state

nodes.call_id

string | null

nodes.stream_id

string | null

nodes.sequence

integer<int64> | null

nodes.role

string | null

nodes.status

string | null

nodes.violation

boolean | null

nodes.effective_violation

boolean | null

nodes.not_sure

boolean | null

nodes.created_at

string | null

nodes.updated_at

string | null

nodes.external_session_id

string | null

edges

object[]

required

Hide child attributes

edges.kind

enum<string>

required

Available options:

parent,

link

edges.source

object

required

Hide child attributes

edges.source.run_id

string

required

edges.source.event_id

string

required

edges.target

object

required

Hide child attributes

edges.target.run_id

string

required

edges.target.event_id

string

required

has_more

boolean

required

next_cursor

string | null

⌘I

cURL

curl --request GET \
  --url https://eu.whitecircle.com/api/runs/{run_id}/graph \
  --header 'Authorization: Bearer <token>' \
  --header 'whitecircle-version: <whitecircle-version>'

import requests

url = "https://eu.whitecircle.com/api/runs/{run_id}/graph"

headers = {
    "whitecircle-version": "<whitecircle-version>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {
    'whitecircle-version': '<whitecircle-version>',
    Authorization: 'Bearer <token>'
  }
};

fetch('https://eu.whitecircle.com/api/runs/{run_id}/graph', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://eu.whitecircle.com/api/runs/{run_id}/graph",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "whitecircle-version: <whitecircle-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://eu.whitecircle.com/api/runs/{run_id}/graph"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("whitecircle-version", "<whitecircle-version>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://eu.whitecircle.com/api/runs/{run_id}/graph")
  .header("whitecircle-version", "<whitecircle-version>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://eu.whitecircle.com/api/runs/{run_id}/graph")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["whitecircle-version"] = '<whitecircle-version>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

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

First Steps

Use Cases

Integrations

Events

Conditions

Artifacts

Policy

Metric

User

Edges and unresolved targets

Authorizations

Headers

Path Parameters

Query Parameters

Response

​Edges and unresolved targets

​Pagination

Authorizations

Headers

Path Parameters

Query Parameters

Response

Edges and unresolved targets

Pagination