Skip to main content
GET
/
api
/
v1
/
sessions
/
{trace_id}
/
spans
Get Trace Spans
curl --request GET \
  --url http://localhost:8000/api/v1/sessions/{trace_id}/spans
[
  {
    "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"
    }
  }
]

Documentation Index

Fetch the complete documentation index at: https://docs.tracectrl.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
trace_id
string
required
The OpenTelemetry trace ID.

​
Query Parameters

​
extra
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:
​
span_id
string
Unique span identifier
​
parent_span_id
string
Parent span ID. Empty string for root spans.
​
span_name
string
Operation name
​
span_kind
string
OTel span kind: INTERNAL, SERVER, CLIENT, etc.
​
service_name
string
Service that emitted this span
​
start_ns
integer
Start time as Unix nanoseconds
​
duration_ns
integer
Duration in nanoseconds
​
status_code
string
STATUS_CODE_OK, STATUS_CODE_ERROR, or STATUS_CODE_UNSET
​
status_message
string
Error message if status is ERROR
​
attributes
object
Full SpanAttributes map — all tracectrl.*, openinference.*, input.*, output.* attributes
​
resource_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"
    }
  }
]