For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Trust CenterStatusSupportGet a demoPlatform
DocumentationEvals API ReferenceIntegrations & OTELPlatform SettingsSelf-HostingChangelog
DocumentationEvals API ReferenceIntegrations & OTELPlatform SettingsSelf-HostingChangelog
  • Get Started
    • Introduction
    • Quickstart
    • Authentication
    • Data Models
    • API Conventions
  • Metrics
    • GETList Metrics
    • POSTCreate Metrics
    • PUTUpdate Metrics
    • POSTBatch Create
  • Metric Collections
    • GETList Metric Collections
    • POSTAdd Collection
    • PUTUpdate Collection
  • Datasets
    • GETList Datasets
    • GETPull Dataset
    • POSTPush Dataset
    • DELDelete Dataset
  • Evaluation
    • POSTRun LLM Evals
    • POSTSimulate Conversation
    • POSTEvaluate Span
    • POSTEvaluate Trace
    • POSTEvaluate Thread
    • GETRetrieve Test Run
    • GETList Test Runs
  • Tracing
    • GETList Traces
    • POSTTrace Ingestion
    • GETRetrieve Trace
    • GETList Spans
    • GETRetrieve Span
  • Threads
    • GETList Threads
    • GETRetrieve Thread
  • Prompt
    • GETList Prompts
    • POSTPush Prompts
    • GETPull Prompts By Label
    • GETPull Prompts By Version
    • GETPull Prompts By Commit
    • GETList Versions
    • POSTCreate Version
    • GETList Commits
    • GETList Branches
    • POSTCreate Branch
    • PUTUpdate Branch
    • DELDelete Branch
  • Metric Data
    • GETList Metrics Data
  • Annotations
    • GETList Annotations
    • POSTCreate Annotation
    • GETGet Annotation
    • PUTUpdate Annotation
  • Annotation Queues
    • GETList Annotation Queues
    • POSTCreate Annotation Queue
    • GETGet Annotation Queue
    • DELDelete Annotation Queue
    • GETList Queue Items
    • POSTAnnotate Queue Item
  • Projects
    • GETList Projects
    • POSTCreate Project
    • PUTUpdate Project
LogoLogo
Trust CenterStatusSupportGet a demoPlatform
Annotations

List Annotations

GET
https://api.confident-ai.com/v1/annotations
GET
/v1/annotations
$curl https://api.confident-ai.com/v1/annotations \
>     -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>"
200Retrieved
1{
2  "success": true,
3  "data": {
4    "annotations": [
5      {
6        "id": "annotation-uuid-1",
7        "rating": 1,
8        "type": "THUMBS_RATING",
9        "name": "Quality Check",
10        "expectedOutput": "Provide clear password reset instructions",
11        "explanation": "Response correctly guides user through password reset",
12        "createdAt": "2025-11-12T10:30:00Z",
13        "traceUuid": "trace-uuid-1",
14        "user": {
15          "id": "user-uuid-1",
16          "email": "user1@example.com",
17          "name": "User One",
18          "image": "https://example.com/user1.png"
19        }
20      },
21      {
22        "id": "annotation-uuid-2",
23        "rating": 5,
24        "type": "FIVE_STAR_RATING",
25        "name": "Customer Service",
26        "expectedOutcome": "Agent successfully resolves user issue",
27        "explanation": "Excellent resolution with follow-up",
28        "createdAt": "2025-11-12T09:15:00Z",
29        "threadId": "thread-id-1",
30        "user": {
31          "id": "user-uuid-2",
32          "email": "user2@example.com",
33          "name": "User Two",
34          "image": "https://example.com/user2.png"
35        }
36      }
37    ],
38    "total": 150,
39    "page": 1,
40    "pageSize": 25
41  }
42}

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.

Was this page helpful?
Previous

Create Annotation

Next
Built with

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

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).

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 createdAt.

Allowed values:
ascendingenumOptional

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

Allowed values:

Response

Successfully retrieved list of annotations
successboolean
Indicates if the request was successful.
dataobject
Contains the list of annotations and pagination information.