---
title: "List Annotations"
method: GET
path: "/v1/annotations"
tags: ["Annotations"]
---

# List Annotations

`GET /v1/annotations`

Retrieves a paginated list of annotations from your Confident AI project. Annotations are user feedback on traces, spans, or threads that include ratings, expected outputs/outcomes, and explanations.

Use query parameters to filter annotations by trace UUID, span UUID, thread ID, type, or rating range. Results are returned in descending order by creation date with pagination support.

## Query parameters

- `traceUuid` string
- `spanUuid` string
- `threadId` string
- `type` 'THUMBS_RATING' | 'FIVE_STAR_RATING'
- `minRating` string
- `maxRating` string
- `page` integer
- `pageSize` integer
- `start` string, date-time
- `end` string, date-time
- `sortBy` 'createdAt'
- `ascending` 'true' | 'false'

## Headers

- `CONFIDENT_API_KEY` string, required

## Response `200`

Successfully retrieved list of annotations

- ListAnnotationsResponse
  - `success` boolean, required — Indicates if the request was successful.
  - `data` object, required — Contains the list of annotations and pagination information.
    - `annotations` Annotation[], required — List of annotations matching the filter criteria.
      - `id` string, required — This is the id of the annotation generated by Confident AI, not to be confused with the alias you supplied or version number.
      - `rating` integer, required — This is the annotated rating score.
      - `type` 'THUMBS_RATING' | 'FIVE_STAR_RATING', required — This is the type of annotation, which can be either thumbs rating or five star rating.
      - `name` string — The name of the annotation.
      - `expectedOutcome` string — This is the annotated expected outcome, for conversation annotations.
      - `expectedOutput` string — This is the annotated expected output, for span and trace annotations.
      - `explanation` string — This is the explanation for the annotation.
      - `createdAt` string, date-time — The timestamp when the annotation was created.
      - `traceUuid` string — The UUID of the trace associated with this annotation, if applicable.
      - `spanUuid` string — The UUID of the span associated with this annotation, if applicable.
      - `threadId` string — The ID of the thread associated with this annotation, if applicable.
      - `testCaseId` string — The ID of the test case associated with this annotation, if applicable.
      - `user` UserReference
        - `id` string, required — The id of the user.
        - `email` string, required — The email address of the user.
        - `name` string, nullable, required — The name of the user.
        - `image` string, nullable, required — The image of the user.
      - `userEmail` string, nullable — The email address of the user created this annotation. The field is being deprecated. Please use `user.email` instead.
    - `total` integer, required — Total number of annotations matching the filter criteria.
    - `page` integer, required — Current page number of annotations returned in this response.
    - `pageSize` integer, required — Maximum number of annotations returned in this response.

## Changes

> 54 revisions in range; 3 not diffed.

- **2026-04-28** `75ac46e3e464` — 2 info
  - added the required property `data/annotations/items/user/allOf[#/components/schemas/UserReference]/id` to the response with the `200` status
  - added the required property `data/annotations/items/user/allOf[#/components/schemas/UserReference]/image` to the response with the `200` status
- **2026-04-28** `0b1be348f19f` — 3 breaking, 4 info
  - the response property `data/annotations/items/userEmail` became nullable for the status `200`
  - removed the required property `data/limit` from the response with the `200` status
  - removed the required property `data/offset` from the response with the `200` status
  - added the optional property `data/annotations/items/user` to the response with the `200` status
  - …3 more
- **2026-03-03** `ecbd18488092` — 2 breaking, 2 info
  - removed the enum value `asc` from the `query` request parameter `ascending`
  - removed the enum value `desc` from the `query` request parameter `ascending`
  - added the new enum value `false` to the `query` request parameter `ascending`
  - added the new enum value `true` to the `query` request parameter `ascending`

[Change history](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/changes/v1/annotations/get.md)

---

[API](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api.md) · [All operations](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/confident-ai/confident-ai-metrics-api/revisions/95cdde71b65e/schema)