---
title: "List spans with simple filters (no DSL)"
method: GET
path: "/v1/projects/{project_identifier}/spans"
tags: ["spans"]
---

# List spans with simple filters (no DSL)

`GET /v1/projects/{project_identifier}/spans`

Return spans within a project filtered by time range. Supports cursor-based pagination.

## Path parameters

- `project_identifier` string, required — The project identifier: either project ID or project name. If using a project name, it cannot contain slash (/), question mark (?), or pound sign (#) characters.

## Query parameters

- `cursor` string, nullable — Pagination cursor (Span Global ID)
- `limit` integer — Maximum number of spans to return
- `start_time` string, date-time, nullable — Inclusive lower bound time
- `end_time` string, date-time, nullable — Exclusive upper bound time
- `trace_id` string[], nullable — Filter by one or more trace IDs
- `span_id` string[], nullable — Filter by one or more span IDs
- `parent_id` string, nullable — Filter by parent span ID. Use "null" to get root spans only.
- `name` string[], nullable — Filter by span name(s)
- `span_kind` string[], nullable — Filter by span kind(s). Values: LLM, CHAIN, TOOL, RETRIEVER, EMBEDDING, AGENT, RERANKER, GUARDRAIL, EVALUATOR, UNKNOWN
- `status_code` string[], nullable — Filter by status code(s). Values: OK, ERROR, UNSET
- `attribute` string[], nullable — Filter spans by `key:value`. Key is a dot-path (e.g. `user.id`, `metadata.tier`). Value is JSON-parsed: `k:12345` is int, `k:true` is bool, otherwise string (`k:user-42`). To match a numeric- or boolean-looking STRING, JSON-quote it: `user.id:"12345"` (URL-encoded `%2212345%22`). Split is on the first `:` only, so values may contain colons (`session.id:sess:abc:123`, ISO timestamps). Repeat the param to AND filters. List-valued attributes (e.g. `tag.tags`) cannot be matched here. Returns 422 on malformed input (missing colon, empty key/value, or list/dict/null value).

## Response `200`

Successful Response

- SpansResponseBody
  - `data` Span[], required
    - `id` string — Span Global ID, distinct from the OpenTelemetry span ID
    - `name` string, required — Name of the span operation
    - `context` SpanContext, required
      - `trace_id` string, required — OpenTelemetry trace ID
      - `span_id` string, required — OpenTelemetry span ID
    - `span_kind` string, required — Type of work that the span encapsulates
    - `parent_id` string, nullable — OpenTelemetry span ID of the parent span
    - `start_time` string, date-time, required — Start time of the span (must be timezone-aware)
    - `end_time` string, date-time, required — End time of the span (must be timezone-aware)
    - `status_code` string, required — Status code of the span
    - `status_message` string — Status message
    - `attributes` object — Span attributes
    - `events` SpanEvent[] — Span events
      - `name` string, required — Name of the event
      - `timestamp` string, date-time, required — When the event occurred (must be timezone-aware)
      - `attributes` object — Event attributes
  - `next_cursor` string, nullable, required

## Other responses

- `403` — Forbidden
- `404` — Not Found
- `422` — Unprocessable Entity

---

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