Get Trace Spans

GET

api

sessions

{trace_id}

spans

Get Trace Spans

curl --request GET \
  --url http://localhost:8000/api/v1/sessions/{trace_id}/spans

const options = {method: 'GET'};

fetch('http://localhost:8000/api/v1/sessions/{trace_id}/spans', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8000",
  CURLOPT_URL => "http://localhost:8000/api/v1/sessions/{trace_id}/spans",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$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 := "http://localhost:8000/api/v1/sessions/{trace_id}/spans"

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

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://localhost:8000/api/v1/sessions/{trace_id}/spans")

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

request = Net::HTTP::Get.new(url)

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

[
  {
    "span_id": "abc123",
    "parent_span_id": "",
    "span_name": "AgentExecutor",
    "span_kind": "INTERNAL",
    "service_name": "my-agent-service",
    "start_ns": 1742222400000000000,
    "duration_ns": 3500000000,
    "status_code": "STATUS_CODE_OK",
    "status_message": "",
    "attributes": {
      "openinference.span.kind": "AGENT",
      "tracectrl.agent.id": "researcher-agent",
      "tracectrl.agent.name": "Researcher",
      "tracectrl.session_id": "a1b2c3d4-e5f6-7890",
      "tracectrl.tool.category": "",
      "input.value": "Summarize my latest emails"
    },
    "resource_attributes": {
      "service.name": "my-agent-service"
    }
  }
]

Returns the flat list of spans for a trace, ordered by timestamp. The frontend builds the parent-child tree from parent_span_id.

Path Parameters

string

required

The OpenTelemetry trace ID.

Query Parameters

string

Comma-separated list of additional trace IDs to merge in (used for OpenClaw multi-trace sessions). All spans are returned sorted by start_ns.

Response

Array of span detail objects:

string

Unique span identifier

string

Parent span ID. Empty string for root spans.

string

Operation name

string

OTel span kind: INTERNAL, SERVER, CLIENT, etc.

string

Service that emitted this span

integer

Start time as Unix nanoseconds

integer

Duration in nanoseconds

string

STATUS_CODE_OK, STATUS_CODE_ERROR, or STATUS_CODE_UNSET

string

Error message if status is ERROR

object

Full SpanAttributes map — all tracectrl.*, openinference.*, input.*, output.* attributes

object

Resource-level attributes (service name, SDK version, etc.)

[
  {
    "span_id": "abc123",
    "parent_span_id": "",
    "span_name": "AgentExecutor",
    "span_kind": "INTERNAL",
    "service_name": "my-agent-service",
    "start_ns": 1742222400000000000,
    "duration_ns": 3500000000,
    "status_code": "STATUS_CODE_OK",
    "status_message": "",
    "attributes": {
      "openinference.span.kind": "AGENT",
      "tracectrl.agent.id": "researcher-agent",
      "tracectrl.agent.name": "Researcher",
      "tracectrl.session_id": "a1b2c3d4-e5f6-7890",
      "tracectrl.tool.category": "",
      "input.value": "Summarize my latest emails"
    },
    "resource_attributes": {
      "service.name": "my-agent-service"
    }
  }
]

Get Trace Spans

curl --request GET \
  --url http://localhost:8000/api/v1/sessions/{trace_id}/spans

const options = {method: 'GET'};

fetch('http://localhost:8000/api/v1/sessions/{trace_id}/spans', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8000",
  CURLOPT_URL => "http://localhost:8000/api/v1/sessions/{trace_id}/spans",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$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 := "http://localhost:8000/api/v1/sessions/{trace_id}/spans"

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

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://localhost:8000/api/v1/sessions/{trace_id}/spans")

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

request = Net::HTTP::Get.new(url)

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

[
  {
    "span_id": "abc123",
    "parent_span_id": "",
    "span_name": "AgentExecutor",
    "span_kind": "INTERNAL",
    "service_name": "my-agent-service",
    "start_ns": 1742222400000000000,
    "duration_ns": 3500000000,
    "status_code": "STATUS_CODE_OK",
    "status_message": "",
    "attributes": {
      "openinference.span.kind": "AGENT",
      "tracectrl.agent.id": "researcher-agent",
      "tracectrl.agent.name": "Researcher",
      "tracectrl.session_id": "a1b2c3d4-e5f6-7890",
      "tracectrl.tool.category": "",
      "input.value": "Summarize my latest emails"
    },
    "resource_attributes": {
      "service.name": "my-agent-service"
    }
  }
]

Engine API

Risk

Scans

Guardrails & Violations

Path Parameters

Query Parameters

Response

​Path Parameters

​Query Parameters

​Response

Path Parameters

Query Parameters

Response