---
title: "Get span annotations filtered by span_ids and/or identifier."
method: GET
path: "/v1/projects/{project_identifier}/span_annotations"
tags: ["annotations"]
---

# Get span annotations filtered by span_ids and/or identifier.

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

Return span annotations for a project, filtered by `span_ids`, `identifier`, or both. At least one of `span_ids` or `identifier` must be supplied. When both are supplied, results are the AND-intersection of the two filters.

## Path parameters

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

## Query parameters

- `span_ids` string[], nullable — Optional list of span ids to fetch annotations for. If omitted, `identifier` must be supplied.
- `identifier` string[], nullable — Optional list of annotation identifiers to filter by. Each value must be non-empty. If omitted, `span_ids` must be supplied. When combined with `span_ids`, results are the AND-intersection of both filters.
- `include_annotation_names` string[], nullable — Optional list of annotation names to include. If provided, only annotations with these names will be returned. 'note' annotations are excluded by default unless explicitly included in this list.
- `exclude_annotation_names` string[], nullable — Optional list of annotation names to exclude from results.
- `cursor` string, nullable — A cursor for pagination
- `limit` integer — The maximum number of annotations to return in a single request

## Response `200`

Successful Response

- SpanAnnotationsResponseBody
  - `data` SpanAnnotation[], required
    - `id` string, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `source` 'API' | 'APP', required
    - `user_id` string, nullable, required
    - `name` string, required — The name of the annotation
    - `annotator_kind` 'LLM' | 'CODE' | 'HUMAN', required — The kind of annotator used for the annotation
    - `result` AnnotationResult
      - `label` string, nullable — The label assigned by the annotation
      - `score` number, nullable — The score assigned by the annotation
      - `explanation` string, nullable — Explanation of the annotation result
    - `metadata` object, nullable — Metadata for the annotation
    - `identifier` string — The identifier of the annotation. If provided, the annotation will be updated if it already exists.
    - `span_id` string, required — OpenTelemetry Span ID (hex format w/o 0x prefix)
  - `next_cursor` string, nullable, required

## Other responses

- `403` — Forbidden
- `404` — Project or spans not found
- `422` — Invalid parameters

## Changes

- **2026-04-30** `4c3ecf13cbaa` — 5 info
  - added the new optional `query` request parameter `identifier`
  - the `query` request parameter `span_ids` became optional
  - `query` request parameter `span_ids` list-of-types was widened by adding types `null`
  - for the `query` request parameter `span_ids`, the minItems was decreased from `1` to `0`
  - …1 more
- **2026-04-29** `c81391216eb5` — 4 breaking, 1 warning
  - the `query` request parameter `span_ids` became required
  - `query` request parameter `span_ids` list-of-types was narrowed by removing types `null`
  - for the `query` request parameter `span_ids`, the minItems was increased from `0` to `1`
  - for the `query` request parameter `span_ids`, the type changed from no type to `array`
  - …1 more

[Change history](https://skmtc.dev/arize-ai/apis/arize-phoenix-rest-api/changes/v1/projects/:project_identifier/span_annotations/get.md)

---

[API](https://skmtc.dev/arize-ai/apis/arize-phoenix-rest-api.md) · [All operations](https://skmtc.dev/arize-ai/apis/arize-phoenix-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/arize-ai/arize-phoenix-rest-api/revisions/4714c409fd3d/schema)