> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create annotation queue 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.</Note>

<Note>This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>




## OpenAPI

````yaml https://api.arize.com/v2/spec.yaml post /v2/annotation-queues/{annotation_queue_id}/records
openapi: 3.0.3
info:
  title: Arize REST API
  version: 2.0.0
  description: |
    API specification for the backend data server. The API is hosted globally
    at https://api.arize.com/v2 or in your own environment.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - description: Global
    url: https://api.arize.com
  - description: Regional
    url: https://api.{region}.arize.com
    variables:
      region:
        default: eu-west-1a
        enum:
          - eu-west-1a
          - ca-central-1a
  - description: Custom Host
    url: https://{host}
    variables:
      host:
        default: api.arize.com
security:
  - bearerAuth: []
tags:
  - name: AI Integrations
    description: |
      AI integrations configure access to external LLM providers (e.g. OpenAI,
      Azure OpenAI, AWS Bedrock, Vertex AI). Integrations can be scoped to the
      entire account, a specific organization, or a specific space.
  - name: Annotation Configs
    description: >
      Annotation configs allow you to define consistent annotation schemas that

      can be reused across your workspace, ensuring evaluations are structured
      and

      comparable over time.
  - name: Annotation Queues
    description: >
      Annotation queues help you organize and manage human evaluation workflows.

      Use queues to assign spans or examples to annotators for review and
      labeling.
  - name: API Keys
    description: >
      API keys are used to authenticate requests to the Arize API. List your
      keys

      to view metadata; the raw secret is never returned after creation.
  - name: Datasets
    description: |
      Datasets are structured, version-controlled example collections you use to
      run, evaluate, and track LLM experiments.
  - name: Evaluators
    description: >
      Evaluators are reusable evaluation configurations used to assess the
      quality

      of LLM outputs. They can be template-based (using LLM judges) or
      code-based.
  - name: Experiments
    description: >
      Experiments let you systematically test prompt/model changes using
      datasets,

      tasks, and evaluators.
  - name: Integrations
    description: >
      Integrations configure access to external LLM providers (e.g. OpenAI,

      Azure OpenAI, AWS Bedrock, Vertex AI), notifications services (e.g.
      PagerDuty, Slack), and

      your own agents. Integrations can be scoped to the entire account, a
      specific

      organization, or a specific space.
  - name: Organizations
    description: >
      Organizations are top-level containers within an Arize AX account for
      grouping spaces.
  - name: Projects
    description: |
      Projects represent LLM applications being monitored in Arize where you can
      observe traces and spans.
  - name: Prompts
    description: >
      Prompts are reusable, versioned templates for LLM interactions. Use
      prompts

      to standardize and manage how you interact with LLMs across your
      application.
  - name: Resource Restrictions
    description: |
      Endpoints for restricting and unrestricting resources (projects, models).
  - name: Role Bindings
    description: |
      Role bindings assign a role to a user on a resource. REST currently
      supports space- and project-scoped bindings.
  - name: Roles
    description: >
      Roles define sets of permissions that can be assigned to users within an

      account. Create custom roles to tailor access control to your team's
      needs.
  - name: Spaces
    description: >
      Spaces are containers within an organization for grouping related
      projects,

      datasets, and experiments, enabling collaboration or isolated
      experimentation

      with role-based access control.
  - name: Spans
    description: |
      Spans represent individual operations within a trace. A span captures the
      timing, status, and attributes of a single operation in your application.
  - name: Tasks
    description: |
      Tasks are configurable units of work that tie one or more evaluators to a
      data source (project or dataset). Use tasks to automate evaluation of LLM
      outputs, with support for continuous evaluation and backfill runs.
  - name: Users
    description: >
      Users represent members of an account. The Users endpoints allow creating,

      listing, updating (display name), and removing users from the account
      programmatically.
paths:
  /v2/annotation-queues/{annotation_queue_id}/records:
    post:
      tags:
        - Annotation Queues
      summary: Create annotation queue records
      description: >
        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.</Note>


        <Note>This endpoint is in beta, read more
        [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>
      operationId: annotation_queues_records_create
      parameters:
        - $ref: '#/components/parameters/AnnotationQueueIdPathParam'
      requestBody:
        $ref: '#/components/requestBodies/AddAnnotationQueueRecordsRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/AnnotationQueueRecordCreate'
        '201':
          $ref: '#/components/responses/AnnotationQueueRecordCreate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
components:
  parameters:
    AnnotationQueueIdPathParam:
      name: annotation_queue_id
      in: path
      description: The unique annotation queue identifier (base64)
      required: true
      schema:
        $ref: '#/components/schemas/Id'
      example: QW5ub3RhdGlvblF1ZXVlOjEyMzQ1
  requestBodies:
    AddAnnotationQueueRecordsRequestBody:
      description: Body containing records to add to an annotation queue
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AddAnnotationQueueRecordsRequestBody'
          example:
            record_sources:
              - record_type: span
                project_id: proj_abc123
                start_time: '2024-01-15T00:00:00Z'
                end_time: '2024-01-15T23:59:59Z'
                span_ids:
                  - span_abc123
                  - span_def456
  responses:
    AnnotationQueueRecordCreate:
      description: Returns the created annotation queue records
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AnnotationQueueRecordCreateResponse'
          example:
            record_sources:
              - id: aqr_001
                annotation_queue_id: aq_abc123
                source_type: spans
                data:
                  input: What is the capital of France?
                  output: Paris
                annotations: []
                evaluations: []
                assigned_users:
                  - user:
                      id: usr_123
                      email: reviewer@example.com
                    completion_status: pending
              - id: aqr_002
                annotation_queue_id: aq_abc123
                source_type: dataset
                data:
                  input: Summarize this article in one sentence.
                  output: The article discusses climate change impacts.
                annotations: []
                evaluations: []
                assigned_users:
                  - user:
                      id: usr_123
                      email: reviewer@example.com
                    completion_status: pending
    BadRequest:
      description: Invalid request
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 400
            title: Invalid request parameters
            detail: The 'name' field is required and must be a non-empty string.
            instance: /resource
            type: https://arize.com/docs/ax/rest-reference/errors#invalid-request
    Unauthorized:
      description: Authentication is required
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 401
            title: Authentication required
            detail: You must be authenticated to access this resource.
            instance: /resource
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#authentication-required
    Forbidden:
      description: Insufficient permissions to access this resource
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 403
            title: Access forbidden
            detail: You do not have permission to access this resource.
            instance: /resource/12345
            type: https://arize.com/docs/ax/rest-reference/errors#access-forbidden
    NotFound:
      description: Not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 404
            title: Resource not found
            detail: The requested resource with ID '12345' was not found.
            instance: /resource/12345
            type: https://arize.com/docs/ax/rest-reference/errors#resource-not-found
    UnprocessableEntity:
      description: Unprocessable entity
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 422
            title: Unprocessable Entity
            detail: Minimum score must be less than maximum score.
            instance: /annotation-configs
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#unprocessable-entity
    RateLimitExceeded:
      description: Rate limit exceeded
      headers:
        Retry-After:
          description: |
            When throttled (429), how long to wait before retrying. Value is
            either a delta-seconds integer.
          schema:
            type: integer
            minimum: 0
          example: 42
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            status: 429
            title: Rate limit exceeded
            detail: >-
              You have exceeded the allowed number of requests. Please try again
              later.
            instance: /resource
            type: >-
              https://arize.com/docs/ax/rest-reference/errors#rate-limit-exceeded
  schemas:
    Id:
      type: string
      description: A universally unique identifier (base64-encoded opaque string).
      example: RW50aXR5OjEyMzQ1
    AddAnnotationQueueRecordsRequestBody:
      type: object
      required:
        - record_sources
      properties:
        record_sources:
          type: array
          minItems: 1
          maxItems: 2
          items:
            $ref: '#/components/schemas/AnnotationQueueRecordInput'
          description: >-
            Record sources to add to the annotation queue. At most 2 record
            sources (projects or datasets) may be provided in a single request.
      additionalProperties: false
    AnnotationQueueRecordCreateResponse:
      type: object
      required:
        - record_sources
      properties:
        record_sources:
          type: array
          items:
            $ref: '#/components/schemas/AnnotationQueueRecord'
          description: The created annotation queue records
      additionalProperties: false
    Problem:
      type: object
      description: RFC 9457 Problem Details
      properties:
        title:
          type: string
          description: A short, human-readable summary of the problem type
        status:
          type: integer
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence of the problem
        type:
          type: string
          format: uri-reference
          description: A URI reference that identifies the problem type
        detail:
          type: string
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem
        instance:
          type: string
          format: uri-reference
          description: >-
            A URI reference that identifies the specific occurrence of the
            problem
      required:
        - title
        - status
      additionalProperties: false
    AnnotationQueueRecordInput:
      oneOf:
        - $ref: '#/components/schemas/AnnotationQueueExampleRecordInput'
        - $ref: '#/components/schemas/AnnotationQueueSpanRecordInput'
        - $ref: '#/components/schemas/AnnotationQueueTraceRecordInput'
      discriminator:
        propertyName: record_type
        mapping:
          example:
            $ref: '#/components/schemas/AnnotationQueueExampleRecordInput'
          span:
            $ref: '#/components/schemas/AnnotationQueueSpanRecordInput'
          trace:
            $ref: '#/components/schemas/AnnotationQueueTraceRecordInput'
    AnnotationQueueRecord:
      type: object
      description: A record in an annotation queue with its data
      required:
        - id
        - annotation_queue_id
        - source_type
        - data
        - annotations
        - evaluations
        - assigned_users
      properties:
        id:
          type: string
          description: The unique identifier for the record
        annotation_queue_id:
          type: string
          description: The annotation queue this record belongs to
        source_type:
          $ref: '#/components/schemas/AnnotationQueueSourceType'
        granularity:
          allOf:
            - $ref: '#/components/schemas/RecordGranularity'
          nullable: true
          description: The granularity of the record, if applicable.
        data:
          type: object
          additionalProperties: true
          description: >-
            Record data as flat key-value pairs containing span or dataset
            fields. Does not include annotation or evaluation columns.
        annotations:
          type: array
          items:
            $ref: '#/components/schemas/Annotation'
          description: Human annotations on this record
        evaluations:
          type: array
          items:
            $ref: '#/components/schemas/Evaluation'
          description: Evaluation results on this record
        assigned_users:
          type: array
          items:
            $ref: '#/components/schemas/AnnotationQueueAssignedUser'
          description: Users assigned to this record
      additionalProperties: false
    AnnotationQueueExampleRecordInput:
      type: object
      required:
        - record_type
        - dataset_id
      properties:
        record_type:
          type: string
          enum:
            - example
          description: >-
            Discriminator identifying this record source as dataset examples.
            Must be `example` for dataset example records.
        dataset_id:
          type: string
          description: The dataset ID these examples belong to
        dataset_version_id:
          type: string
          description: >
            Optional. The specific dataset version to use. If omitted, the
            latest version is used.
        example_ids:
          type: array
          items:
            type: string
          description: >
            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.
      additionalProperties: false
    AnnotationQueueSpanRecordInput:
      type: object
      required:
        - record_type
        - project_id
        - span_ids
        - start_time
        - end_time
      properties:
        record_type:
          type: string
          enum:
            - span
          description: >-
            Discriminator identifying this record source as project spans. Must
            be `span` for span records.
        project_id:
          type: string
          description: The project ID these spans belong to
        start_time:
          type: string
          format: date-time
          description: >
            Start of the time range to search for spans in Druid. The range
            (end_time - start_time) must not exceed 7 days.
        end_time:
          type: string
          format: date-time
          description: |
            End of the time range. Must be after start_time.
        span_ids:
          type: array
          items:
            type: string
          minItems: 1
          description: List of span IDs to add to the queue
      additionalProperties: false
    AnnotationQueueTraceRecordInput:
      type: object
      required:
        - record_type
        - project_id
        - trace_ids
        - start_time
        - end_time
      properties:
        record_type:
          type: string
          enum:
            - trace
          description: Discriminator identifying this record as a trace record.
        project_id:
          type: string
          description: The project ID these traces belong to.
        start_time:
          type: string
          format: date-time
          description: >
            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:
          type: string
          format: date-time
          description: |
            End of the time range. Must be after start_time.
        trace_ids:
          type: array
          items:
            type: string
          minItems: 1
          description: |
            List of trace IDs to add to the queue.
      additionalProperties: false
    AnnotationQueueSourceType:
      type: string
      enum:
        - spans
        - dataset
      description: |
        Source type of the annotation queue record.
        - spans - The record originates from span data.
        - dataset - The record originates from a dataset example.
    RecordGranularity:
      type: string
      enum:
        - span
        - trace
      description: |
        Granularity of an annotation queue record.
        - span: The record represents a span.
        - trace: The record represents a trace.
    Annotation:
      type: object
      description: A human annotation on a record.
      required:
        - name
      properties:
        name:
          type: string
          description: The name of the annotation
        score:
          type: number
          format: double
          description: Numeric score for the annotation
        label:
          type: string
          description: Categorical label for the annotation
        text:
          type: string
          description: Free-form text note for the annotation
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the annotation was last updated
        annotator:
          allOf:
            - $ref: '#/components/schemas/AnnotatorUser'
          description: The user who made this annotation
      additionalProperties: false
    Evaluation:
      type: object
      description: An evaluation result on a record.
      required:
        - name
      properties:
        name:
          type: string
          description: The name of the evaluation
        score:
          type: number
          format: double
          description: Numeric score for the evaluation
        label:
          type: string
          description: Categorical label for the evaluation
        explanation:
          type: string
          description: Explanation for the evaluation result
      additionalProperties: false
    AnnotationQueueAssignedUser:
      type: object
      description: A user assigned to a record with their completion status
      required:
        - user
        - completion_status
      properties:
        user:
          $ref: '#/components/schemas/AnnotatorUser'
        completion_status:
          $ref: '#/components/schemas/AnnotationQueueCompletionStatus'
      additionalProperties: false
    AnnotatorUser:
      type: object
      description: A user assigned as an annotator, identified by ID and email.
      required:
        - id
        - email
      properties:
        id:
          type: string
          description: The unique identifier for the user
        email:
          $ref: '#/components/schemas/Email'
      additionalProperties: false
    AnnotationQueueCompletionStatus:
      type: string
      enum:
        - pending
        - completed
      description: |
        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.
    Email:
      type: string
      format: email
      description: An email address
      example: user@example.com
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: <api-key>
      description: >
        Most Arize AI endpoints require authentication. For those endpoints that
        require authentication, include your API key in the request header using
        the format

        ``` Authorization: Bearer <api-key>

        ```

````