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 byroot_span_id. - Each trace returns at most 1,000 spans. When a trace has more, its
spans_truncatedflag istrue.
Authorizations
Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format
Query Parameters
Maximum items to return
1 <= x <= 50Opaque pagination cursor returned from a previous response
(pagination.next_cursor). Treat it as an unreadable token; do not
attempt to parse or construct it.
Body
Body containing trace query parameters
The project ID to list traces for
Return traces whose spans start at or after this timestamp (inclusive).
ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Defaults to 1 week ago.
Return traces whose spans start before this timestamp (exclusive).
ISO 8601 format (e.g., 2024-01-02T00:00:00Z). Defaults to the current time.
Filter expression to apply to the query. Supports SQL-like syntax for
filtering spans by attributes (e.g., status_code = 'ERROR' or
span_kind = 'LLM'). A trace is returned when any of its spans
matches the filter — the matching span is usually a child, not the root.
Optional; omit it to apply no filter. If provided, it must not be empty
or whitespace-only.