List Annotations

(v1)

GET

Retrieves a paginated list of annotations — user feedback on traces, spans, or threads with ratings, expected outputs/outcomes, and explanations. Filter by trace UUID, span UUID, thread ID, type, or rating range; results are ordered by creation date, newest first.

GET/v1/annotations

curl -X GET "https://api.confident-ai.com/v1/annotations" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>"

200

{
  "success": true,
  "data": {
    "annotations": [
      {
        "id": "annotation-uuid-1",
        "rating": 1,
        "type": "THUMBS_RATING",
        "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",
        "user": {
          "id": "user-uuid-1",
          "email": "user1@example.com",
          "name": "User One",
          "image": "https://example.com/user1.png"
        }
      },
      {
        "id": "annotation-uuid-2",
        "rating": 5,
        "type": "FIVE_STAR_RATING",
        "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",
        "user": {
          "id": "user-uuid-2",
          "email": "user2@example.com",
          "name": "User Two",
          "image": "https://example.com/user2.png"
        }
      }
    ],
    "total": 150,
    "page": 1,
    "pageSize": 25
  }
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Query parameters

traceUuidstring
Filter annotations by trace UUID.
spanUuidstring
Filter annotations by span UUID.
threadIdstring
Filter annotations by thread ID.
typeenum
Filter annotations by type.
minRatingstring
Filter annotations with minimum rating (inclusive).
maxRatingstring
Filter annotations with maximum rating (inclusive).
pageinteger
This specifies the page number of the annotations to return. Defaulted to 1.
pageSizeinteger
This specifies the maximum number of annotations per page. Defaulted to 25.
startstring
This filters for annotations created after the specified start datetime. Defaulted to 30 days ago.
endstring
This filters for annotations created before the specified end datetime. Defaulted to the current time.
sortByenum
This determines the field to sort by. Defaulted to createdAt.
ascendingenum
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.
Show 4 propertiesHide 4 properties
- annotationslist of objects
  List of annotations matching the filter criteria.
  Show 14 propertiesHide 14 properties
  - idstring
    This is the id of the annotation generated by Confident AI, not to be confused with the alias you supplied or version number.
  - ratinginteger
    This is the annotated rating score.
  - typeenum
    This is the type of annotation, which can be either thumbs rating or five star rating.
    Show 2 enum valuesHide 2 enum values
    THUMBS_RATING
    FIVE_STAR_RATING
  - namestring
    The name of the annotation.
  - expectedOutcomestring
    This is the annotated expected outcome, for conversation annotations.
  - expectedOutputstring
    This is the annotated expected output, for span and trace annotations.
  - explanationstring
    This is the explanation for the annotation.
  - createdAtstring
    The timestamp when the annotation was created.
  - traceUuidstring
    The UUID of the trace associated with this annotation, if applicable.
  - spanUuidstring
    The UUID of the span associated with this annotation, if applicable.
  - threadIdstring
    The ID of the thread associated with this annotation, if applicable.
  - testCaseIdstring
    The ID of the test case associated with this annotation, if applicable.
  - userobject
    The user who created this annotation.
    Show 4 propertiesHide 4 properties
    idstring
    The id of the user.
    emailstring
    The email address of the user.
    namestring
    The name of the user.
    imagestring
    The image of the user.
  - userEmailstring
    The email address of the user created this annotation. The field is being deprecated. Please use user.email instead.
- totalinteger
  Total number of annotations matching the filter criteria.
- pageinteger
  Current page number of annotations returned in this response.
- pageSizeinteger
  Maximum number of annotations returned in this response.

Built byConfident AI