---
title: "List traces"
method: POST
path: "/v2/traces"
tags: ["Traces"]
---

# List traces

`POST /v2/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](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>

## Query parameters

- `limit` integer
- `cursor` string

## Request body

- ListTracesRequest
  - `project_id` string, required — The project ID to list traces for
  - `start_time` string, date-time — 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.
  - `end_time` string, date-time — 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` string — 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.

## Response `200`

Returns a list of traces

- ListTracesResponse
  - `traces` Trace[], required — A list of traces, ordered newest-first.
    - `trace_id` string, required — Unique identifier for the trace.
    - `root_span_id` string, required — Span ID of the root span (the span with no parent) that anchors this trace entry. A trace with more than one root span is returned as multiple entries sharing the same `trace_id`, distinguished by `root_span_id`.
    - `start_time` string, date-time — Earliest span start time across the returned spans.
    - `end_time` string, date-time — Latest span end time across the returned spans.
    - `spans_truncated` boolean, required — `true` when this trace contained more spans than the per-trace limit and its returned span list is incomplete. `false` otherwise. Note: each page also has an overall cap on the total number of spans returned across all of its traces. On pages that include unusually large traces, an individual trace may return fewer spans than it actually has even when `spans_truncated` is `false`. To retrieve a trace's spans in full, narrow the time window or fetch them directly with `POST /v2/spans` filtered to that `trace_id`.
    - `spans` Span[], required — Flat list of spans belonging to this trace. Each span has the same shape and enrichment as spans returned by `POST /v2/spans`. Reconstruct the trace tree client-side using each span's `parent_id`.
      - `name` string, required — Name of the span
      - `context` SpanContext, required
        - `trace_id` string, required — Unique identifier for the trace this span belongs to
        - `span_id` string, required — Unique identifier for the span
      - `kind` 'LLM' | 'CHAIN' | 'RETRIEVER' | 'EMBEDDING' | 'AGENT' | 'TOOL' | 'RERANKER' | 'GUARDRAIL' | 'EVALUATOR' | 'PROMPT' | 'UNKNOWN', required — The kind of span (OpenInference span kind).
      - `parent_id` string — ID of the parent span
      - `start_time` string, date-time, required — Timestamp when the span started
      - `end_time` string, date-time, required — Timestamp when the span ended
      - `status_code` 'OK' | 'ERROR' | 'UNSET' — Status code of the span. - OK - The operation completed successfully. - ERROR - The operation failed with an error. - UNSET - No status code was set (default, treated as OK).
      - `status_message` string — Status message associated with the span
      - `attributes` object — Key-value pairs of span attributes
      - `annotations` Annotation[] — List of span-level human annotations on this span
        - `name` string, required — The name of the annotation
        - `score` number, double — Numeric score for the annotation
        - `label` string — Categorical label for the annotation
        - `text` string — Free-form text note for the annotation
        - `updated_at` string, date-time — Timestamp when the annotation was last updated
        - `annotator` AnnotatorUser — A user assigned as an annotator, identified by ID and email.
          - `id` string, required — The unique identifier for the user
          - `email` string, email, required — An email address
      - `trace_annotations` Annotation[] — List of trace-level human annotations on this span
        - `name` string, required — The name of the annotation
        - `score` number, double — Numeric score for the annotation
        - `label` string — Categorical label for the annotation
        - `text` string — Free-form text note for the annotation
        - `updated_at` string, date-time — Timestamp when the annotation was last updated
        - `annotator` AnnotatorUser — A user assigned as an annotator, identified by ID and email.
          - `id` string, required — The unique identifier for the user
          - `email` string, email, required — An email address
      - `evaluations` Evaluation[] — List of evaluation results on this span
        - `name` string, required — The name of the evaluation
        - `score` number, double — Numeric score for the evaluation
        - `label` string — Categorical label for the evaluation
        - `explanation` string — Explanation for the evaluation result
      - `events` SpanEvent[] — List of events that occurred during the span
        - `name` string, required — Name of the event
        - `timestamp` string, date-time, required — Timestamp when the event occurred
        - `attributes` object — Key-value pairs of event attributes
  - `pagination` PaginationMetadata, required — Cursor-based pagination metadata. Use `next_cursor` in the subsequent request's `cursor` query parameter.
    - `next_cursor` string — Opaque cursor for fetching the next page. Treat as an unreadable token. Present when `has_more` is true; omitted when `has_more` is false.
    - `has_more` boolean, required — True if another page of results is available.

## Other responses

- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `422` — Unprocessable entity
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/versions/2ce448f1de13/schema)