Skip to main content
GET
Get trace detail with spans and events

Authorizations

Authorization
string
header
required

SDK API key (tl_...) or Clerk session JWT

Path Parameters

id
string<uuid>
required

Response

Trace detail

id
string<uuid>
required
project_id
string<uuid>
required
error
string | null
required
tags
string[]
required
started_at
string<date-time>
required
session_id
string | null
external_id
string | null
name
string | null
input
string | null
output
string | null
model
string | null
latency_ms
integer | null
cost
number | null
total_token_count
integer | null

Sum of prompt_tokens + completion_tokens across every span on the trace, computed at ingest time (TRU-250). Zero when no span reports token usage. Traces ingested before the column existed remain at zero until re-ingested. Queryable via token_count_min / token_count_max on GET /v1/traces.

prompt_tokens_total
integer | null

Sum of prompt tokens across every span on the trace, computed at ingest time.

completion_tokens_total
integer | null

Sum of completion tokens across every span on the trace, computed at ingest time.

tag_map
object

User-defined key→value tag map persisted to the dedicated tags column (TRU-215). Omitted when the trace has no tags. Pre-TRU-215 traces stay without this field until re-ingested.

metadata
object
span_count
integer
control_loop_depth
integer | null

Number of executed retry control_actions rows attached to this trace (TRU-362). Escalations are excluded from the count — once an attempt is auto-converted to escalate, it does not advance the depth. Omitted on the trace list response; populated only on the trace detail response.

spans
object[]
ended_at
string<date-time> | null