---
title: "Batch Annotate Queue Items"
method: POST
path: "/v1/annotation-queues/{name}/batch-annotate"
tags: ["Annotation Queues"]
---

# Batch Annotate Queue Items

`POST /v1/annotation-queues/{name}/batch-annotate`

## Request

- Base URL: `https://api.confident-ai.com`
- URL: `https://api.confident-ai.com/v1/annotation-queues/{name}/batch-annotate`
- Auth: none declared
- TypeScript: <https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/docs/v1/annotation-queues/:name/batch-annotate/post.ts> (a function with typed inputs; its response is checked against the schema)

Annotates many items in a queue in one request. Each entry in `items` carries a `queueItemId` plus the same body as the single-item annotate endpoint.

`annotatorEmail` and `markAsCompleted` set at the top level act as defaults applied to any item that omits them; a per-item value takes precedence.

## Request body

- BatchAnnotate
  - `annotatorEmail` string, email: Default annotator for items that omit it. A per-item `annotatorEmail` takes precedence. Required (here or per item) whenever an item submits `formResponses`.
  - `markAsCompleted` boolean: Default completion flag for items that omit it (effectively `true`). A per-item value takes precedence.
  - `items` BatchAnnotateItem[], required: The items to annotate. Processed independently (best-effort).
    - `queueItemId` string, required: The id of the queue item to annotate.
    - `rating` integer: Rating value for a single criterion (0-1 for THUMBS_RATING, 1-5 for FIVE_STAR_RATING). Shorthand for a one-entry `annotations` array.
    - `type` 'THUMBS_RATING' | 'FIVE_STAR_RATING': Type of the rating.
    - `name` string: Criterion name. Omit for the default criterion; otherwise it must match a configured custom criterion (or a form criteria field), or the annotation will not appear.
    - `expectedOutcome` string: Expected outcome (for thread items only).
    - `expectedOutput` string: Expected output (for trace/span items only).
    - `explanation` string: Explanation for the rating.
    - `annotations` AnnotateCriteria[]: One entry per criterion. Use instead of the flat fields to rate multiple criteria in a single request.
      - `rating` integer, required: Rating value (0-1 for THUMBS_RATING, 1-5 for FIVE_STAR_RATING).
      - `type` 'THUMBS_RATING' | 'FIVE_STAR_RATING': Type of the rating.
      - `name` string: Criterion name. Omit for the default criterion; otherwise it must match a configured custom criterion or a form criteria field.
      - `explanation` string: Explanation for the rating.
      - `expectedOutput` string: Expected output (for trace/span items only).
      - `expectedOutcome` string: Expected outcome (for thread items only).
    - `formResponses` AnnotateFormResponse[]: Answers to a form's custom fields, addressed by each field's visible label. Accepted only for queues with an attached form, and requires `annotatorEmail`.
      - `label` string, required: The visible label of the custom field being answered. Must be unique within the form and must not be a criteria field's label.
      - `value` union: The answer, shaped to the field type. Null clears the answer.
        - string: Text or single-select fields.
        - number: Number or decimal fields.
        - boolean: Yes/No fields (also accepts the strings "Yes"/"No").
        - string[]: Multi-select fields.
    - `annotatorEmail` string, email: Project member to attribute the work to. Required when submitting `formResponses`, otherwise they will not appear in the platform.
    - `markAsCompleted` boolean: Whether to mark the queue item as completed. For form queues, completing enforces the form's required fields.

## Response `200`

Batch processed; inspect each result's `success` flag

- BatchAnnotateResponse
  - `success` boolean, required: Indicates the batch request was well-formed and processed. Per-item outcomes are in `data.results`.
  - `data` object, required
    - `results` BatchAnnotateResult[], required
      - `queueItemId` string, required
      - `success` boolean, required
      - `id` string, nullable: First created annotation's id (success only; null when only form responses were submitted).
      - `annotationIds` string[]: Identifiers of the created annotations (success only).
      - `formResponseIds` string[]: Identifiers of the created form responses (success only).
      - `error` string: Why this item failed (failure only).

## Changes

> 54 revisions in range; 3 not diffed.

- **2026-06-24** `877d6d6d5a76`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/changes/v1/annotation-queues/:name/batch-annotate/post.md)

---

[API](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api.md) - [All operations](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/revisions/95cdde71b65e?raw)