List traces
Returns a paginated list of traces for a project, each carrying its full (flat) list of spans plus lightweight roll-up metadata. It accepts the same project_id, filter, and time-range parameters as POST /v2/spans; the filter uses the identical expression syntax, so there's no separate filter language to learn.
Filtering is trace-contains-match: the syntax matches /v2/spans, but the semantics differ — a filter selects traces that contain at least one matching span (e.g. status_code = 'ERROR' or span_kind = 'LLM'), not only traces whose root span matches. The matching span is usually a child, not the root.
Traces are returned newest-first.
Behaviors and limitations
- Traces are anchored on their root span (the span with no parent). A trace with no root span in the requested time window is omitted.
- Trace assembly is scoped to the requested time window: spans of a boundary-straddling trace that fall outside the range are not included.
- A trace with more than one root span is returned as multiple entries sharing the same trace_id, distinguished by root_span_id.
- Each trace returns at most 1,000 spans. When a trace has more, its spans_truncated flag is true.
<Note>This endpoint is in beta, read more here.</Note>
Query parameters
Maximum items to return
Opaque pagination cursor returned from a previous response (pagination.next_cursor). Treat it as an unreadable token; do not attempt to parse or construct it.
Request body
Response
Returns a list of traces
Example response
{
"traces": [
{
"spans": [
{
"annotations": [
{
"annotator": {
"email": "user@example.com"
}
}
],
"trace_annotations": [
{
"annotator": {
"email": "user@example.com"
}
}
]
}
]
}
]
}