List Annotations | Confident AI Docs

import requests
url = "https://api.confident-ai.com/v1/annotations"
headers = {"CONFIDENT_API_KEY": "<PROJECT-API-KEY>"}
response = requests.get(url, headers=headers)
print(response.json())

{
  "success": true,
  "data": {
    "annotations": [
      {
        "id": "annotation-uuid-1",
        "rating": 1,
        "type": "THUMBS_RATING",
        "flagged": false,
        "name": "Quality Check",
        "expectedOutput": "Provide clear password reset instructions",
        "explanation": "Response correctly guides user through password reset",
        "createdAt": "2025-11-12T10:30:00Z",
        "traceUuid": "trace-uuid-1"
      },
      {
        "id": "annotation-uuid-2",
        "rating": 5,
        "type": "FIVE_STAR_RATING",
        "flagged": false,
        "name": "Customer Service",
        "expectedOutcome": "Agent successfully resolves user issue",
        "explanation": "Excellent resolution with follow-up",
        "createdAt": "2025-11-12T09:15:00Z",
        "threadId": "thread-id-1"
      }
    ],
    "total": 150,
    "limit": 1,
    "offset": 1
  }
}

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, explanations, and flags.

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

Query parameters

traceUuidstringOptional

Filter annotations by trace UUID.

spanUuidstringOptional

Filter annotations by span UUID.

threadIdstringOptional

Filter annotations by thread ID.

typeenumOptional

Filter annotations by type.

Allowed values:

minRatingstringOptional

Filter annotations with minimum rating (inclusive).

maxRatingstringOptional

Filter annotations with maximum rating (inclusive).

flaggedenumOptional

Filter annotations by flagged status.

Allowed values:

pageintegerOptional>=1

This specifies the page number of the annotations to return. Defaulted to 1.

pageSizeintegerOptional>=1

This specifies the maximum number of annotations per page. Defaulted to 25.

startstringOptionalformat: "date-time"

This filters for annotations created after the specified start datetime. Defaulted to 30 days ago.

endstringOptionalformat: "date-time"

This filters for annotations created before the specified end datetime. Defaulted to the current time.

sortByenumOptional

This determines the field to sort by. Defaulted to created_at.

Allowed values:

ascendingbooleanOptional

This determines if the field specified in sortBy should be in ascending order. Defaults to false.

Response

Successfully retrieved list of annotations

successboolean

Indicates if the request was successful.

dataobject

Contains the list of annotations and pagination information.

Headers

Query parameters

Response