Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lumiqtrace.com/llms.txt

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

The traces endpoint retrieves every span belonging to a single trace and returns them as a nested tree. This is the same data structure that powers the Trace Viewer in the LumiqTrace dashboard. Use it to programmatically inspect multi-step LLM pipelines, identify which span caused a failure, or measure latency across each step in a chain.

​
Endpoint

GET https://api.lumiqtrace.com/v1/traces/:traceId
Authentication: Authorization: Bearer <token> (see Authentication)

​
Path Parameters

​
traceId
string
required
The trace_id shared by all spans in the trace you want to retrieve. This is the same value you set on events when you ingested them.

​
Query Parameters

​
projectId
string
required
The ID of the project that owns this trace.

​
Example Request

curl "https://api.lumiqtrace.com/v1/traces/trace-abc?projectId=proj_abc123" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Response

200 OK — Returns an array of root spans. Each span may contain a children array of child spans, forming a recursive tree. 
[
  {
    "event_id": "550e8400-e29b-41d4-a716-446655440001",
    "trace_id": "trace-abc",
    "span_id": "span-001",
    "parent_span_id": null,
    "timestamp": "2026-04-20T10:00:00.000Z",
    "provider": "openai",
    "model": "gpt-4o",
    "operation": "chat",
    "latency_ms": 2100,
    "ttft_ms": 340,
    "input_tokens": 1024,
    "output_tokens": 256,
    "cost_usd": 0.0068,
    "status": "success",
    "stream": true,
    "environment": "production",
    "user_id": "user_4421",
    "sdk_version": "1.4.2",
    "children": [
      {
        "event_id": "550e8400-e29b-41d4-a716-446655440002",
        "trace_id": "trace-abc",
        "span_id": "span-002",
        "parent_span_id": "span-001",
        "timestamp": "2026-04-20T10:00:00.150Z",
        "provider": "openai",
        "model": "text-embedding-3-small",
        "operation": "embed",
        "latency_ms": 120,
        "input_tokens": 64,
        "output_tokens": 0,
        "cost_usd": 0.000013,
        "status": "success",
        "stream": false,
        "environment": "production",
        "sdk_version": "1.4.2",
        "children": []
      }
    ]
  }
]
​
span_id
string
Unique identifier for this span within the trace.
​
parent_span_id
string | null
The span_id of the parent span. null for root spans.
​
children
Span[]
Recursively nested child spans. An empty array means this span is a leaf node.
All other fields on each span match the LumiqEvent schema. The only addition is the children array, which is not present in the raw event.

​
Understanding the Span Tree

Root spans are LLM calls that were not triggered by another LLM call — typically the first call in a pipeline. Child spans are calls that occurred inside the context of a parent call, such as an embedding lookup performed during a RAG retrieval step. If a span in your application is not appearing as a child of the expected parent, verify that its parent_span_id is set to the correct span_id and that both spans share the same trace_id.