---
title: "Create annotation queue records"
method: POST
path: "/v2/annotation-queues/{annotation_queue_id}/records"
tags: ["Annotation Queues"]
---

# Create annotation queue records

`POST /v2/annotation-queues/{annotation_queue_id}/records`

Add new records from spans, traces, or dataset examples to an existing annotation queue.

**Payload Requirements**
  - At least one record source is required.
  - At most 2 record sources are allowed per request
  - For span record source: `start_time` must be before `end_time`, and the range must not exceed 7 days.
  - For dataset record source: all `example_ids` must be non-empty strings.
  - For project record source:
    - span records: all `span_ids` must be non-empty strings.
    - trace records: all `trace_ids` must be non-empty strings.
  - At most 500 records total may be added in one request

**Valid example (span record)**
```json
{
  "record_sources": [
    {
      "record_type": "SPAN",
      "project_id": "TW9kZWw6MTIzOmFCY0Q=",
      "start_time": "2026-01-15T00:00:00Z",
      "end_time": "2026-01-16T00:00:00Z",
      "span_ids": ["U3BhbjoxOmFCY0Q="]
    }
  ]
}
```

**Valid example (trace record)**
```json
{
  "record_sources": [
    {
      "record_type": "TRACE",
      "project_id": "TW9kZWw6MTIzOmFCY0Q=",
      "start_time": "2026-01-15T00:00:00Z",
      "end_time": "2026-01-16T00:00:00Z",
      "trace_ids": ["8fe3373f-0da4-4a8e-b57f-5c8878cfb747"]
    }
  ]
}
```

**Invalid example** (span record with `start_time` after `end_time`)
```json
{
  "record_sources": [
    {
      "record_type": "SPAN",
      "project_id": "TW9kZWw6MTIzOmFCY0Q=",
      "start_time": "2026-01-20T00:00:00Z",
      "end_time": "2026-01-15T00:00:00Z",
      "span_ids": ["U3BhbjoxOmFCY0Q="]
    }
  ]
}
```

<Note>If no example_ids are provided for a dataset record source, all examples in the dataset will be added to the queue only when the total records from all sources does not exceed 500.</Note>

**Response codes**
- `201 Created`: at least one new record was added to the queue.
- `200 OK`: the request was valid but all record sources were already present
  in the queue — no new records were inserted. The `record_sources` array in
  the response body will be empty.

## Path parameters

- `annotation_queue_id` string, required — A universally unique identifier (base64-encoded opaque string).

## Request body

- AddAnnotationQueueRecordsRequest
  - `record_sources` AnnotationQueueRecordInput[], required — Record sources to add to the annotation queue. At most 2 record sources (projects or datasets) may be provided in a single request. The total number of records resolved from all sources must not exceed 500.
    - union
      - AnnotationQueueExampleRecordInput
        - `record_type` 'EXAMPLE', required — Discriminator identifying this record source as dataset examples. Must be `EXAMPLE` for dataset example records.
        - `dataset_id` string, required — The dataset ID these examples belong to
        - `dataset_version_id` string — Optional. The specific dataset version to use. If omitted, the latest version is used.
        - `example_ids` string[] — Optional. List of example IDs within the dataset to add to the queue. If omitted, all examples in the dataset (or dataset version) are added, provided the total records from all sources does not exceed 500.
      - AnnotationQueueSpanRecordInput
        - `record_type` 'SPAN', required — Discriminator identifying this record source as project spans. Must be `SPAN` for span records.
        - `project_id` string, required — The project ID these spans belong to
        - `start_time` string, date-time, required — Start of the time range to search for spans. The range (end_time - start_time) must not exceed 7 days.
        - `end_time` string, date-time, required — End of the time range. Must be after start_time.
        - `span_ids` string[], required — List of span IDs to add to the queue
      - AnnotationQueueTraceRecordInput
        - `record_type` 'TRACE', required — Discriminator identifying this record as a trace record.
        - `project_id` string, required — The project ID these traces belong to.
        - `start_time` string, date-time, required — Start of the time range used to resolve each trace's root span. The range (end_time - start_time) must not exceed 7 days.
        - `end_time` string, date-time, required — End of the time range. Must be after start_time.
        - `trace_ids` string[], required — List of trace IDs to add to the queue.

## Response `200`

Returns the created annotation queue records

- CreateAnnotationQueueRecordResponse
  - `record_sources` AnnotationQueueRecord[], required — The created annotation queue records
    - `id` string, required — The unique identifier for the record
    - `annotation_queue_id` string, required — The annotation queue this record belongs to
    - `source_type` 'SPANS' | 'DATASET', required — Source type of the annotation queue record. - SPANS - The record originates from span data. - DATASET - The record originates from a dataset example.
    - `granularity` 'SPAN' | 'TRACE' — Granularity of an annotation queue record. - SPAN: The record represents a span. - TRACE: The record represents a trace.
    - `data` object, required — Record data as flat key-value pairs containing span or dataset fields. Does not include annotation or evaluation columns.
    - `annotations` Annotation[], required — Annotations on this record.
      - `name` string, required — The name of the annotation
      - `score` number, double — Numeric score for the annotation
      - `label` string — Categorical label for the annotation
      - `text` string — Free-form text note for the annotation
      - `updated_at` string, date-time — Timestamp when the annotation was last updated
      - `annotator` AnnotatorUser — A user assigned as an annotator, identified by ID and email.
        - `id` string, required — The unique identifier for the user
        - `email` string, email, required — An email address
    - `trace_annotations` Annotation[], required — Trace annotations on this record.
      - `name` string, required — The name of the annotation
      - `score` number, double — Numeric score for the annotation
      - `label` string — Categorical label for the annotation
      - `text` string — Free-form text note for the annotation
      - `updated_at` string, date-time — Timestamp when the annotation was last updated
      - `annotator` AnnotatorUser — A user assigned as an annotator, identified by ID and email.
        - `id` string, required — The unique identifier for the user
        - `email` string, email, required — An email address
    - `evaluations` Evaluation[], required — Evaluation results on this record
      - `name` string, required — The name of the evaluation
      - `score` number, double — Numeric score for the evaluation
      - `label` string — Categorical label for the evaluation
      - `explanation` string — Explanation for the evaluation result
    - `assigned_users` AnnotationQueueAssignedUser[], required — Users assigned to this record
      - `user` AnnotatorUser, required — A user assigned as an annotator, identified by ID and email.
        - `id` string, required — The unique identifier for the user
        - `email` string, email, required — An email address
      - `completion_status` 'PENDING' | 'COMPLETED', required — Completion status for a user's annotation assignment on a record. - PENDING - The user has not yet submitted annotations. - COMPLETED - The user has submitted annotations.

## Other responses

- `201` — Returns the created annotation queue records
- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `422` — Unprocessable entity
- `429` — Rate limit exceeded

---

[API](https://skmtc.dev/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.dev/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/revisions/6521535a37bb/schema)