List Annotations

GEThttps://api.confident-ai.com/v2/annotations

Lists the annotations in your Confident AI project one page at a time, newest first by default. Filter by the trace, span or thread they were left on, by rating scale, and by time window.

GET/v2/annotations

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

200

{
  "success": true,
  "data": {
    "annotations": [
      {
        "id": "<ANNOTATION-ID>",
        "rating": 1,
        "type": "FIVE_STAR_RATING",
        "name": null,
        "explanation": "Correct and concise.",
        "expectedOutcome": null,
        "expectedOutput": "The capital of France is Paris.",
        "createdAt": "2025-01-15T11:00:00.000Z",
        "user": {
          "id": "<USER-ID>",
          "email": "jane@acme.com",
          "name": "Jane Doe",
          "image": null
        },
        "traceUuid": "3f9c2a1e-5b7d-4c8e-9f01-2a3b4c5d6e7f",
        "spanUuid": null,
        "threadId": null,
        "testCaseId": null
      }
    ],
    "totalAnnotations": 1,
    "page": 1,
    "pageSize": 25
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Query parameters

pageintegerdefault: 1
The page of annotations to return. Defaults to 1.
pageSizeintegerdefault: 25
The number of annotations per page, at most 100. Defaults to 25.
startstring
Returns only annotations left at or after this ISO 8601 datetime. Defaults to 60 days ago.
endstring
Returns only annotations left before this ISO 8601 datetime. Defaults to the current time.
sortByenumdefault: createdAt
This determines the field to sort by. Defaults to createdAt.
ascendingenumdefault: false
This determines if the field specified in sortBy should be in ascending order. Defaults to false, which returns the newest annotations first.
traceUuidstring
Returns only annotations left on this trace.
spanUuidstring
Returns only annotations left on this span.
threadIdstring
Returns only annotations left on this thread.
typeenum
Returns only annotations recorded on this scale.

Response

List Annotations succeeded.

successboolean
Indicates if the request was successful.
dataobject
One page of annotations, with the total across all pages.
Show 4 propertiesHide 4 properties
- annotationslist of objects
  The annotations for the current page.
  Show 13 propertiesHide 13 properties
  - idstring
    This is the id of the annotation generated by Confident AI.
  - 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
    FIVE_STAR_RATING
    THUMBS_RATING
  - namestring | null
    The name of the annotation.
  - explanationstring | null
    This is the explanation for the annotation.
  - expectedOutcomestring | null
    This is the annotated expected outcome, for conversation annotations.
  - expectedOutputstring | null
    This is the annotated expected output, for span and trace annotations.
  - createdAtstring
    The timestamp when the annotation was created.
  - userobject | null
    A Confident AI user, as referenced by the records they created.
    Show 4 propertiesHide 4 properties
    idstring
    This is the id of the user.
    emailstring
    This is the email address of the user.
    namestring | null
    This is the display name of the user, or null when they have not set one.
    imagestring | null
    This is the URL of the user's avatar, or null when they have none.
  - traceUuidstring | null
    The uuid of the trace this annotation was left on, or null when it was left on a span or thread.
  - spanUuidstring | null
    The uuid of the span this annotation was left on, or null when it was left on a trace or thread.
  - threadIdstring | null
    The id of the thread this annotation was left on. It is also set for an annotation on a trace that belongs to a thread.
  - testCaseIdstring | null
    The id of the test case the annotated trace formed, for a trace ingested into a test run.
- totalAnnotationsinteger
  The total number of annotations matching the query across all pages.
- pageinteger
  The page this response covers.
- pageSizeinteger
  The number of annotations per page.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI