---
title: "List spans"
method: POST
path: "/v2/spans"
tags: ["Spans"]
---

# List spans

`POST /v2/spans`

Returns a paginated list of spans.

The spans are sorted by their timestamp, with the most recent coming first.

<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

- ListSpansRequest
  - `project_id` string, required — The project ID to list spans for
  - `start_time` string, date-time — Filter to spans starting 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 — Filter to spans starting 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'`). Optional; omit it to apply no filter. If provided, it must not be empty or whitespace-only.

## Response `200`

Returns a list of spans

- ListSpansResponse
  - `spans` Span[], required — A list of spans
    - `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)