> ## 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.

# Annotate a batch of project spans

> Write human annotations to a batch of spans in a project.

**Idempotency**: Writes use upsert semantics — submitting the same annotation
config name for the same span overwrites the previous value. Retrying on
network failure will not create duplicates.

**202 Accepted**: The annotations have been accepted and will be written.
Visibility in read queries may lag by a short interval.

**Partial failure**: Writes are grouped by calendar day and processed
sequentially. A non-2xx response means the request failed during the write
phase — annotations for earlier calendar-day buckets may already be saved
while later ones are not. It is safe to retry the full request;
re-submitting a record that was already saved will overwrite it with the
same value (no duplicates).

**Payload Requirements**
- `project_id` is required and must identify a project the caller has span annotation access to.
- `annotations` is a list of per-span annotation inputs. Each entry identifies
  one span by its `record_id` and provides one or more annotation values.
- Each `record_id` must be unique within the request (duplicates return 400).
- Each record's `values` list must not contain duplicate annotation config names (returns 400).
- `start_time` / `end_time` constrain the Druid time range for span lookup.
  If omitted, `start_time` defaults to 31 days ago and `end_time` to now.
  Both `start_time` and `end_time` may not be in the future. The window may
  not exceed 31 days. If ANY span ID cannot be located within the given
  range, the entire request is rejected with 404 and no annotations are
  written (all-or-nothing pre-validation). Only after all spans are
  confirmed does the write phase begin.
- Annotation names must match existing annotation configs in the project's space.
- Up to 1000 span records may be annotated per request.

**Valid example**
```json
{
  "project_id": "proj_abc123",
  "annotations": [
    {"record_id": "span_abc", "values": [{"name": "relevance", "label": "good", "score": 1.0}]}
  ]
}
```

**Invalid example** (annotation name not found in space)
```json
{
  "project_id": "proj_abc123",
  "annotations": [
    {"record_id": "span_abc", "values": [{"name": "nonexistent_config"}]}
  ]
}
```

**Invalid example** (time window exceeds 31 days)
```json
{
  "project_id": "proj_abc123",
  "start_time": "2025-01-01T00:00:00Z",
  "end_time": "2025-03-01T00:00:00Z",
  "annotations": [
    {"record_id": "span_abc", "values": [{"name": "relevance", "label": "good"}]}
  ]
}
```

<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/spans/annotate
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/spans/annotate:
    post:
      tags:
        - Spans
      summary: Annotate a batch of project spans
      description: >
        Write human annotations to a batch of spans in a project.


        **Idempotency**: Writes use upsert semantics — submitting the same
        annotation

        config name for the same span overwrites the previous value. Retrying on

        network failure will not create duplicates.


        **202 Accepted**: The annotations have been accepted and will be
        written.

        Visibility in read queries may lag by a short interval.


        **Partial failure**: Writes are grouped by calendar day and processed

        sequentially. A non-2xx response means the request failed during the
        write

        phase — annotations for earlier calendar-day buckets may already be
        saved

        while later ones are not. It is safe to retry the full request;

        re-submitting a record that was already saved will overwrite it with the

        same value (no duplicates).


        **Payload Requirements**

        - `project_id` is required and must identify a project the caller has
        span annotation access to.

        - `annotations` is a list of per-span annotation inputs. Each entry
        identifies
          one span by its `record_id` and provides one or more annotation values.
        - Each `record_id` must be unique within the request (duplicates return
        400).

        - Each record's `values` list must not contain duplicate annotation
        config names (returns 400).

        - `start_time` / `end_time` constrain the Druid time range for span
        lookup.
          If omitted, `start_time` defaults to 31 days ago and `end_time` to now.
          Both `start_time` and `end_time` may not be in the future. The window may
          not exceed 31 days. If ANY span ID cannot be located within the given
          range, the entire request is rejected with 404 and no annotations are
          written (all-or-nothing pre-validation). Only after all spans are
          confirmed does the write phase begin.
        - Annotation names must match existing annotation configs in the
        project's space.

        - Up to 1000 span records may be annotated per request.


        **Valid example**

        ```json

        {
          "project_id": "proj_abc123",
          "annotations": [
            {"record_id": "span_abc", "values": [{"name": "relevance", "label": "good", "score": 1.0}]}
          ]
        }

        ```


        **Invalid example** (annotation name not found in space)

        ```json

        {
          "project_id": "proj_abc123",
          "annotations": [
            {"record_id": "span_abc", "values": [{"name": "nonexistent_config"}]}
          ]
        }

        ```


        **Invalid example** (time window exceeds 31 days)

        ```json

        {
          "project_id": "proj_abc123",
          "start_time": "2025-01-01T00:00:00Z",
          "end_time": "2025-03-01T00:00:00Z",
          "annotations": [
            {"record_id": "span_abc", "values": [{"name": "relevance", "label": "good"}]}
          ]
        }

        ```


        <Note>This endpoint is in beta, read more
        [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>
      operationId: spans_annotate
      requestBody:
        $ref: '#/components/requestBodies/AnnotateSpansRequestBody'
      responses:
        '202':
          $ref: '#/components/responses/SpansAnnotated'
        '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:
  requestBodies:
    AnnotateSpansRequestBody:
      description: Body containing span annotation batch
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AnnotateSpansRequestBody'
          example:
            project_id: proj_abc123
            start_time: '2024-01-01T00:00:00Z'
            end_time: '2024-01-08T00:00:00Z'
            annotations:
              - record_id: span_abc
                values:
                  - name: relevance
                    label: good
                    score: 0.9
  responses:
    SpansAnnotated:
      description: Annotations accepted. Writes are idempotent; retry on failure is safe.
    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:
    AnnotateSpansRequestBody:
      type: object
      description: Batch annotation request for project spans.
      required:
        - project_id
        - annotations
      properties:
        project_id:
          type: string
          description: The project (model) ID whose spans are being annotated.
          example: proj_abc123
        start_time:
          type: string
          format: date-time
          description: >-
            Start of the time range for span lookup. Optional; defaults to 31
            days ago.
          example: '2024-01-01T00:00:00Z'
        end_time:
          type: string
          format: date-time
          description: End of the time range for span lookup. Optional; defaults to now.
          example: '2024-01-08T00:00:00Z'
        annotations:
          type: array
          minItems: 1
          maxItems: 1000
          items:
            $ref: '#/components/schemas/AnnotateRecordInput'
          description: Batch of span annotations to write. Up to 1000 spans per request.
      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
    AnnotateRecordInput:
      type: object
      description: A single record to annotate in a batch, identified by its record ID.
      required:
        - record_id
        - values
      properties:
        record_id:
          type: string
          description: >-
            The record identifier (span ID, dataset example ID, or experiment
            run ID, depending on the endpoint).
        values:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/AnnotationInput'
          description: One or more annotation values to set on this record.
      additionalProperties: false
    AnnotationInput:
      type: object
      description: >-
        An annotation value to set on a record, identified by its annotation
        config name. Omitting a field leaves the existing value unchanged.
      required:
        - name
      properties:
        name:
          type: string
          description: The annotation config name
          example: accuracy
        score:
          type: number
          format: double
          description: Numeric score for the annotation. Omit to leave unchanged.
        label:
          type: string
          description: Categorical label for the annotation. Omit to leave unchanged.
        text:
          type: string
          description: Free-form text note for the annotation. Omit to leave unchanged.
      additionalProperties: false
  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>

        ```

````