Launch Week 3: Five days of launches

Items

Overview

The Confident AI SDK exposes every Item method on the platform. This page documents how to call these methods in all supported languages. See the introduction to install the SDK and set your API key.

Methods

List Items

Lists the items in an annotation queue one page at a time, oldest first. Filter by status to see only what is still waiting to be annotated, only what a reviewer has set aside, or only what is done.

from confident_ai import ConfidentAI
from confident_ai.annotation_queues import QueueItemStatus

client = ConfidentAI()

result = client.annotation_queues.list_items(
    annotation_queue_id="<ANNOTATION-QUEUE-ID>",
    page=1,
    page_size=25,
    status=QueueItemStatus.IN_PROGRESS,
)

For async mode, call a_list_items and await it as shown below:

result = await client.annotation_queues.a_list_items(...)

Parameters

ParameterTypeDescription
annotation_queue_idstrRequired. The id of the annotation queue.
pageOptional[int]The page of items to return. Defaults to 1.
page_sizeOptional[int]The number of items per page, at most 100. Defaults to 25.
statusOptional[QueueItemStatus]Returns only items in this state. Omit to return every item whatever its state. See QueueItemStatus.

Returns

This method returns an object of type AnnotationQueueItemList.

Add Trace Queue Items

Adds production data to an annotation queue and returns the ids of the items created. Send the list that matches the queue's type; every id must already exist in your project, and anything already in the queue is skipped.

Traces to add to a TRACE queue.

from confident_ai import ConfidentAI
from confident_ai.annotation_queues import AddTraceQueueItemsRequest

client = ConfidentAI()

result = client.annotation_queues.add_items(
    annotation_queue_id="<ANNOTATION-QUEUE-ID>",
    items=AddTraceQueueItemsRequest(
        trace_uuids=["3f9c2a1e-5b7d-4c8e-9f01-2a3b4c5d6e7f"]
    ),
)

For async mode, call a_add_items and await it as shown below:

result = await client.annotation_queues.a_add_items(...)

Parameters

ParameterTypeDescription
annotation_queue_idstrRequired. The id of the annotation queue.
itemsAddQueueItemsRequestRequired. The production data to add to the queue. Send the list that matches the queue's type — traceUuids for a TRACE queue, spanUuids for a SPAN queue, threadIds for a THREAD queue — and every id must already exist in your project. Items already in the queue are skipped. Pass one of AddTraceQueueItemsRequest, AddSpanQueueItemsRequest, AddThreadQueueItemsRequest. See AddQueueItemsRequest.

Returns

This method returns an object of type AddedQueueItems.

Add Span Queue Items

Adds production data to an annotation queue and returns the ids of the items created. Send the list that matches the queue's type; every id must already exist in your project, and anything already in the queue is skipped.

Spans to add to a SPAN queue.

from confident_ai import ConfidentAI
from confident_ai.annotation_queues import AddSpanQueueItemsRequest

client = ConfidentAI()

result = client.annotation_queues.add_items(
    annotation_queue_id="<ANNOTATION-QUEUE-ID>",
    items=AddSpanQueueItemsRequest(
        span_uuids=["9d2c6f7e-1a3b-4c5d-8e9f-0a1b2c3d4e5f"]
    ),
)

For async mode, call a_add_items and await it as shown below:

result = await client.annotation_queues.a_add_items(...)

Parameters

ParameterTypeDescription
annotation_queue_idstrRequired. The id of the annotation queue.
itemsAddQueueItemsRequestRequired. The production data to add to the queue. Send the list that matches the queue's type — traceUuids for a TRACE queue, spanUuids for a SPAN queue, threadIds for a THREAD queue — and every id must already exist in your project. Items already in the queue are skipped. Pass one of AddTraceQueueItemsRequest, AddSpanQueueItemsRequest, AddThreadQueueItemsRequest. See AddQueueItemsRequest.

Returns

This method returns an object of type AddedQueueItems.

Add Thread Queue Items

Adds production data to an annotation queue and returns the ids of the items created. Send the list that matches the queue's type; every id must already exist in your project, and anything already in the queue is skipped.

Threads to add to a THREAD queue.

from confident_ai import ConfidentAI
from confident_ai.annotation_queues import AddThreadQueueItemsRequest

client = ConfidentAI()

result = client.annotation_queues.add_items(
    annotation_queue_id="<ANNOTATION-QUEUE-ID>",
    items=AddThreadQueueItemsRequest(
        thread_ids=["thread-42"]
    ),
)

For async mode, call a_add_items and await it as shown below:

result = await client.annotation_queues.a_add_items(...)

Parameters

ParameterTypeDescription
annotation_queue_idstrRequired. The id of the annotation queue.
itemsAddQueueItemsRequestRequired. The production data to add to the queue. Send the list that matches the queue's type — traceUuids for a TRACE queue, spanUuids for a SPAN queue, threadIds for a THREAD queue — and every id must already exist in your project. Items already in the queue are skipped. Pass one of AddTraceQueueItemsRequest, AddSpanQueueItemsRequest, AddThreadQueueItemsRequest. See AddQueueItemsRequest.

Returns

This method returns an object of type AddedQueueItems.

Annotate Item

Records your team's annotation of one queue item and marks it complete, returning the ids of what was written. Send annotations for criteria ratings, formResponses for answers to the queue's annotation form, or both; answering the form requires annotatorEmail.

from confident_ai import ConfidentAI
from confident_ai.annotation_queues import QueueItemAnnotation
from confident_ai.annotation_queues import QueueItemFormResponse

client = ConfidentAI()

result = client.annotation_queues.annotate_item(
    annotation_queue_id="<ANNOTATION-QUEUE-ID>",
    queue_item_id="<QUEUE-ITEM-ID>",
    annotations=[
        QueueItemAnnotation(
            field_type="THUMBS_RATING",
            value=True,
            name="Helpfulness",
            explanation="Answered the question and cited the right source.",
            expected_output="Mount Everest is 8,848 metres tall.",
            expected_outcome="The user learns how tall Mount Everest is.",
            images_mapping={}
        )
    ],
    form_responses=[
        QueueItemFormResponse(
            label="How helpful was the answer?",
            value="Very helpful"
        )
    ],
    annotator_email="jane@acme.com",
    flagged=False,
    mark_as_completed=True,
)

For async mode, call a_annotate_item and await it as shown below:

result = await client.annotation_queues.a_annotate_item(...)

Parameters

ParameterTypeDescription
annotation_queue_idstrRequired. The id of the annotation queue the item belongs to.
queue_item_idstrRequired. The id of the queue item.
annotationsOptional[List[QueueItemAnnotation]]The criteria ratings to record on the item, one entry per criterion. See QueueItemAnnotation.
form_responsesOptional[List[QueueItemFormResponse]]The annotations for the fields of the queue's annotation form. Sending them requires annotatorEmail. See QueueItemFormResponse.
annotator_emailOptional[str]The email address of the project member the work is credited to. Required when formResponses are sent, and what makes the annotation visible on the platform.
flaggedOptional[bool]Whether to flag the item for a second opinion.
mark_as_completedOptional[bool]Whether to mark the item annotated, taking it out of the pending list. Defaults to true.

Returns

This method returns an object of type AnnotateQueueItemResult.

Types

AddQueueItemsRequest

The production data to add to the queue. Send the list that matches the queue's type — traceUuids for a TRACE queue, spanUuids for a SPAN queue, threadIds for a THREAD queue — and every id must already exist in your project. Items already in the queue are skipped.

AddQueueItemsRequest = Union[
    AddTraceQueueItemsRequest,
    AddSpanQueueItemsRequest,
    AddThreadQueueItemsRequest,
]

A AddQueueItemsRequest is one of the shapes below. Send the fields of one of them, never a mix of both.

Traces to add to a TRACE queue.

class AddTraceQueueItemsRequest:
    trace_uuids: List[str] = Field(alias="traceUuids")

trace_uuidsList[str]Required

The uuids of the traces to add.

Example: ["3f9c2a1e-5b7d-4c8e-9f01-2a3b4c5d6e7f"]

AddedQueueItems

The items created by adding production data to a queue.

class AddedQueueItems:
    ids: List[str]

idsList[str]Required

The ids of the queue items created, one per item that was not already in the queue.

Example: ["<QUEUE-ITEM-ID>"]

AnnotateQueueItemResult

What one item's annotation wrote.

class AnnotateQueueItemResult:
    annotation_ids: List[str] = Field(alias="annotationIds")
    form_response_ids: List[str] = Field(alias="formResponseIds")

annotation_idsList[str]Required

The ids of the annotations recorded, one per criterion rated.

Example: ["<ANNOTATION-ID>"]

form_response_idsList[str]Required

The ids of the form answers recorded, one per field answered.

Example: ["<ANNOTATION-FORM-RESPONSE-ID>"]

AnnotationQueueItem

One piece of production data waiting to be annotated. Retrieve the trace, span or thread it names for the payload to show your annotator.

class AnnotationQueueItem:
    id: str
    trace_uuid: Optional[str] = Field(alias="traceUuid")
    span_uuid: Optional[str] = Field(alias="spanUuid")
    thread_id: Optional[str] = Field(alias="threadId")
    test_case_id: Optional[str] = Field(alias="testCaseId")
    added_at: str = Field(alias="addedAt")
    status: QueueItemStatus
    assigned_to_email: Optional[str] = Field(alias="assignedToEmail")

idstrRequired

The id of the queue item, generated by Confident AI.

Example: "<QUEUE-ITEM-ID>"

trace_uuidOptional[str]Required

The uuid of the trace waiting to be annotated, or null for an item of another kind.

Example: "3f9c2a1e-5b7d-4c8e-9f01-2a3b4c5d6e7f"

span_uuidOptional[str]Required

The uuid of the span waiting to be annotated, or null for an item of another kind.

thread_idOptional[str]Required

The id of the thread waiting to be annotated, or null for an item of another kind.

test_case_idOptional[str]Required

The id of the test case waiting to be annotated, for a queue Confident AI created from a test run.

added_atstrRequired

When the item was added to the queue.

Example: "2025-01-15T10:30:00+00:00"

statusQueueItemStatusRequired

assigned_to_emailOptional[str]Required

The email address of the reviewer this item is assigned to, or null when it is open to anyone.

Example: "jane@acme.com"

AnnotationQueueItemList

One page of queue items, with the total across all pages.

class AnnotationQueueItemList:
    items: List[AnnotationQueueItem]
    total_annotation_queue_items: int = Field(alias="totalAnnotationQueueItems")
    page: int
    page_size: int = Field(alias="pageSize")

itemsList[AnnotationQueueItem]Required

The items for the current page, oldest first.

See AnnotationQueueItem.

total_annotation_queue_itemsintRequired

The total number of items matching the query.

Example: 40

pageintRequired

The page this response covers.

Example: 1

page_sizeintRequired

The number of items per page.

Example: 25

MLLMImage

An image referenced from a text field by a [DEEPEVAL:IMAGE:<key>] marker. Send either a public url or the bytes in base64.

class MLLMImage:
    url: str
    local: bool
    base64: Optional[str] = None
    filename: Optional[str] = None
    mime_type: Optional[str] = Field(default=None, alias="mimeType")
    data_base64: Optional[str] = Field(default=None, alias="dataBase64")

urlstrRequired

This is the URL of the image.

Example: "https://example.com/everest.png"

localboolRequired

This is true when the image is your local file.

Example: false

base64Optional[str]

The base64 data of the image.

Example: "iVBORw0KGgo="

filenameOptional[str]

The original file name.

Example: "everest.png"

mime_typeOptional[str]

The image's MIME type.

Example: "image/png"

data_base64Optional[str]

The image encoded as a base64 data URL.

Example: "data:image/png;base64,iVBORw0KGgo="

QueueItemAnnotation

One rating, as an annotator would leave it on the item. fieldType defaults to THUMBS_RATING.

class QueueItemAnnotation:
    field_type: Optional[Literal["THUMBS_RATING", "FIVE_STAR_RATING"]] = Field(default=None, alias="fieldType")
    value: Union[bool, int]
    name: Optional[str] = None
    explanation: Optional[str] = None
    expected_output: Optional[str] = Field(default=None, alias="expectedOutput")
    expected_outcome: Optional[str] = Field(default=None, alias="expectedOutcome")
    images_mapping: Optional[Dict[str, MLLMImage]] = Field(default=None, alias="imagesMapping")

field_typeOptional[Literal["THUMBS_RATING", "FIVE_STAR_RATING"]]

The kind of rating. Defaults to THUMBS_RATING.

valueUnion[bool, int]Required

The rating to record: true or false for a THUMBS_RATING, 1 to 5 for a FIVE_STAR_RATING.

Example: true

nameOptional[str]

A name for what this rating is for. On a queue with a form, it matches a rating field's label; on a queue without one, omit it for the default rating.

Example: "Helpfulness"

explanationOptional[str]

Why the rating was given.

Example: "Answered the question and cited the right source."

expected_outputOptional[str]

The output the target should have produced. Only for an item holding a trace or span.

Example: "Mount Everest is 8,848 metres tall."

expected_outcomeOptional[str]

The outcome the conversation should have reached. Only for an item holding a thread.

Example: "The user learns how tall Mount Everest is."

images_mappingOptional[Dict[str, MLLMImage]]

Images referenced by [DEEPEVAL:IMAGE:<key>] markers in the text fields, keyed by that marker's key.

See MLLMImage.

QueueItemFormResponse

One annotation on a field of the queue's annotation form.

class QueueItemFormResponse:
    label: str
    value: Optional[Any] = None

labelstrRequired

The label of the form field being answered, exactly as the form spells it.

Example: "How helpful was the answer?"

valueOptional[Any]

The annotation value, in the shape the field's type expects: a string for TEXT, a number for NUMBER or FLOAT, a boolean for BOOLEAN, one of the options in the field's config for CHOICE, and a list of them for MULTIPLE_CHOICE.

Example: "Very helpful"

QueueItemStatus

Where an item stands in the review: IN_PROGRESS before work starts, DRAFT after work is autosaved but before it is submitted, DEFERRED once a reviewer has set it aside to come back to, and COMPLETED once it has been submitted.

class QueueItemStatus(Enum):
    IN_PROGRESS = "IN_PROGRESS"
    DRAFT = "DRAFT"
    DEFERRED = "DEFERRED"
    COMPLETED = "COMPLETED"

IN_PROGRESS · DRAFT · DEFERRED · COMPLETED

Building a production pipeline?Design a scalable API workflow for evals, datasets, traces, and promptsTalk to an engineer

Last updated on

Built byConfident AI