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

# Create alignment run

> Scores how closely one evaluator version's labels matched the human
annotations on a dataset version, using the column pair and comparison
function named by the alignment task in the path.

Scoring is synchronous: the score is computed before the response is
returned, so the created run already carries its `score` and
`comparable_row_count`. There is no run to poll for.

**A run that could not be scored still returns `201`.** The run resource was
created, so it is returned with `status: FAILED` and a public
`failed_reason`. Backend error details are kept in server logs.
A failed score is not a server error and is not reported as `5xx`. Check
`status` on every response rather than relying on the status code alone.

Read `score` and `comparable_row_count` together. `score` is `null`, not
`0`, when no row had both a judge label and a human annotation: nothing was
comparable, so no agreement was measured. A `score` of `0` means rows were
compared and none agreed. A high `score` over a small
`comparable_row_count` is not a meaningful result.

A finished run is never rewritten. Scoring the same version again creates
another run, because both the annotations and the task's columns can change
between scores.

**Payload Requirements**
- `evaluator_version_id` is required: the evaluator version to score. The
  caller must have update access to the evaluator that owns it.
- `dataset_version_id` is required and must belong to the alignment task's
  dataset. A dataset version from another dataset returns `404`, the same as
  one that does not exist.
- `predicted_entity` is required and names what produced the judge labels:
  `entity_type: DATASET_VERSION` when the labels were already on the
  dataset, or `entity_type: EXPERIMENT` when an experiment produced them.
  An entity that does not belong to the same dataset returns `404`.
- System-managed fields (`id`, `created_at`, `updated_at`, `status`,
  `score`, `comparable_row_count`, `failed_reason`) are rejected on input.
  `alignment_task_id` is taken from the path and is rejected in the body.

The response records `predicted_entity` on successful and failed runs.
Malformed IDs, incorrect field types, and a body that is not an object
return `400`. Missing required values, unsupported entity types, and
unknown fields return `422`.

**Valid example**
```json
{
  "evaluator_version_id": "RXZhbHVhdG9yVmVyc2lvbjoxMDpYeVp3",
  "dataset_version_id": "RGF0YXNldFZlcnNpb246NTY6UXJTdA==",
  "predicted_entity": {
    "id": "RGF0YXNldFZlcnNpb246NTY6UXJTdA==",
    "entity_type": "DATASET_VERSION"
  }
}
```

**Invalid example** (`score` is computed by the server and cannot be supplied)
```json
{
  "evaluator_version_id": "RXZhbHVhdG9yVmVyc2lvbjoxMDpYeVp3",
  "dataset_version_id": "RGF0YXNldFZlcnNpb246NTY6UXJTdA==",
  "predicted_entity": {
    "id": "RGF0YXNldFZlcnNpb246NTY6UXJTdA==",
    "entity_type": "DATASET_VERSION"
  },
  "score": 0.9
}
```

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




## OpenAPI

````yaml https://api.arize.com/v2/spec.yaml post /v2/alignment-tasks/{alignment_task_id}/runs
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: Alignment
    description: >
      Alignment measures agreement between evaluator labels and human
      annotations.

      Tasks define the dataset columns and comparison function. Runs record the

      resulting score for a dataset version.
  - 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: Audit Logs
    description: >
      Audit logs record authenticated user actions within an account, providing
      a

      chronological trail for security and compliance review. Access requires

      account admin privileges and audit logging to be enabled.
  - name: Dashboards
    description: >
      Dashboards organize charts and summaries that help teams understand their
      data.
  - 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: Monitors
    description: >
      Monitors continuously track a metric over your model or LLM application
      data

      and alert you when it crosses a threshold. Each monitor watches a single

      metric - data quality, model performance, drift, a custom metric, or a

      tracing metric - and moves between statuses as the metric passes in and
      out of its 

      healthy range.
  - 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: SAML
    description: Enterprise account-admin SAML configuration and role mappings.
  - 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: Tags
    description: |
      Tags are reusable labels defined once per space and attached to resources
      across the platform, so the same vocabulary can be applied to projects,
      datasets, prompts, and more. Tags are shared: renaming or deleting a tag
      affects every resource it is attached to.
  - 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: Traces
    description: |
      A trace is the collection of spans sharing a trace ID, representing a
      single end-to-end request through an LLM application. Use the Traces
      endpoint to retrieve traces with all of their spans in one call.
  - 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.
  - name: Webhooks
    description: >
      Webhooks are organization-owned destinations that receive event deliveries

      over HTTPS. Deliveries are authenticated with a bearer token or signed
      with

      an HMAC signing secret — the secret is returned exactly once, when the

      webhook is created. Delivery attempts are recorded and can be listed for

      debugging. To choose which events a webhook receives, manage its

      subscriptions through the prompt and evaluator webhook-subscription

      endpoints.
paths:
  /v2/alignment-tasks/{alignment_task_id}/runs:
    post:
      tags:
        - Alignment
      summary: Create alignment run
      description: >
        Scores how closely one evaluator version's labels matched the human

        annotations on a dataset version, using the column pair and comparison

        function named by the alignment task in the path.


        Scoring is synchronous: the score is computed before the response is

        returned, so the created run already carries its `score` and

        `comparable_row_count`. There is no run to poll for.


        **A run that could not be scored still returns `201`.** The run resource
        was

        created, so it is returned with `status: FAILED` and a public

        `failed_reason`. Backend error details are kept in server logs.

        A failed score is not a server error and is not reported as `5xx`. Check

        `status` on every response rather than relying on the status code alone.


        Read `score` and `comparable_row_count` together. `score` is `null`, not

        `0`, when no row had both a judge label and a human annotation: nothing
        was

        comparable, so no agreement was measured. A `score` of `0` means rows
        were

        compared and none agreed. A high `score` over a small

        `comparable_row_count` is not a meaningful result.


        A finished run is never rewritten. Scoring the same version again
        creates

        another run, because both the annotations and the task's columns can
        change

        between scores.


        **Payload Requirements**

        - `evaluator_version_id` is required: the evaluator version to score.
        The
          caller must have update access to the evaluator that owns it.
        - `dataset_version_id` is required and must belong to the alignment
        task's
          dataset. A dataset version from another dataset returns `404`, the same as
          one that does not exist.
        - `predicted_entity` is required and names what produced the judge
        labels:
          `entity_type: DATASET_VERSION` when the labels were already on the
          dataset, or `entity_type: EXPERIMENT` when an experiment produced them.
          An entity that does not belong to the same dataset returns `404`.
        - System-managed fields (`id`, `created_at`, `updated_at`, `status`,
          `score`, `comparable_row_count`, `failed_reason`) are rejected on input.
          `alignment_task_id` is taken from the path and is rejected in the body.

        The response records `predicted_entity` on successful and failed runs.

        Malformed IDs, incorrect field types, and a body that is not an object

        return `400`. Missing required values, unsupported entity types, and

        unknown fields return `422`.


        **Valid example**

        ```json

        {
          "evaluator_version_id": "RXZhbHVhdG9yVmVyc2lvbjoxMDpYeVp3",
          "dataset_version_id": "RGF0YXNldFZlcnNpb246NTY6UXJTdA==",
          "predicted_entity": {
            "id": "RGF0YXNldFZlcnNpb246NTY6UXJTdA==",
            "entity_type": "DATASET_VERSION"
          }
        }

        ```


        **Invalid example** (`score` is computed by the server and cannot be
        supplied)

        ```json

        {
          "evaluator_version_id": "RXZhbHVhdG9yVmVyc2lvbjoxMDpYeVp3",
          "dataset_version_id": "RGF0YXNldFZlcnNpb246NTY6UXJTdA==",
          "predicted_entity": {
            "id": "RGF0YXNldFZlcnNpb246NTY6UXJTdA==",
            "entity_type": "DATASET_VERSION"
          },
          "score": 0.9
        }

        ```


        <Warning>This endpoint is in alpha, read more
        [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Warning>
      operationId: create_alignment_run
      parameters:
        - $ref: '#/components/parameters/AlignmentTaskIdPathParam'
      requestBody:
        $ref: '#/components/requestBodies/CreateAlignmentRunRequestBody'
      responses:
        '201':
          $ref: '#/components/responses/AlignmentRun'
        '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:
    AlignmentTaskIdPathParam:
      name: alignment_task_id
      in: path
      required: true
      description: The unique alignment task identifier (base64)
      schema:
        $ref: '#/components/schemas/Id'
      example: T25saW5lVGFzazoxMjphQmNE
  requestBodies:
    CreateAlignmentRunRequestBody:
      description: Body containing alignment run parameters.
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateAlignmentRunRequest'
          examples:
            dataset_version_labels:
              summary: Score labels already present on the dataset
              value:
                evaluator_version_id: RXZhbHVhdG9yVmVyc2lvbjoxMDpYeVp3
                dataset_version_id: RGF0YXNldFZlcnNpb246NTY6UXJTdA==
                predicted_entity:
                  id: RGF0YXNldFZlcnNpb246NTY6UXJTdA==
                  entity_type: DATASET_VERSION
            experiment_labels:
              summary: Score labels produced by an experiment
              value:
                evaluator_version_id: RXZhbHVhdG9yVmVyc2lvbjoxMDpYeVp3
                dataset_version_id: RGF0YXNldFZlcnNpb246NTY6UXJTdA==
                predicted_entity:
                  id: RXhwZXJpbWVudDo3ODpMbU5v
                  entity_type: EXPERIMENT
  responses:
    AlignmentRun:
      description: Returns the created alignment run
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AlignmentRun'
          examples:
            scored:
              summary: A run that scored successfully
              value:
                id: RXZhbEFsaWdubWVudFRhc2tSdW46MzQ6YUJjRA==
                created_at: '2026-02-13T21:27:19.055Z'
                updated_at: '2026-02-13T21:27:21.402Z'
                alignment_task_id: T25saW5lVGFzazoxMjphQmNE
                evaluator_version_id: RXZhbHVhdG9yVmVyc2lvbjoxMDpYeVp3
                dataset_version_id: RGF0YXNldFZlcnNpb246NTY6UXJTdA==
                predicted_entity:
                  entity_type: DATASET_VERSION
                  id: RGF0YXNldFZlcnNpb246NTY6UXJTdA==
                status: COMPLETED
                score: 0.82
                comparable_row_count: 440
                failed_reason: null
            nothing_to_compare:
              summary: >-
                A run where no row had both labels, so there was nothing to
                score
              value:
                id: RXZhbEFsaWdubWVudFRhc2tSdW46MzU6YUJjRA==
                created_at: '2026-02-13T21:30:02.118Z'
                updated_at: '2026-02-13T21:30:03.771Z'
                alignment_task_id: T25saW5lVGFzazoxMjphQmNE
                evaluator_version_id: RXZhbHVhdG9yVmVyc2lvbjoxMDpYeVp3
                dataset_version_id: RGF0YXNldFZlcnNpb246NTc6UXJTdA==
                predicted_entity:
                  entity_type: DATASET_VERSION
                  id: RGF0YXNldFZlcnNpb246NTc6UXJTdA==
                status: COMPLETED
                score: null
                comparable_row_count: 0
                failed_reason: null
            failed:
              summary: A run that could not be scored, still returned as a created run
              value:
                id: RXZhbEFsaWdubWVudFRhc2tSdW46MzY6YUJjRA==
                created_at: '2026-02-13T21:33:44.900Z'
                updated_at: '2026-02-13T21:33:45.210Z'
                alignment_task_id: T25saW5lVGFzazoxMjphQmNE
                evaluator_version_id: RXZhbHVhdG9yVmVyc2lvbjoxMDpYeVp3
                dataset_version_id: RGF0YXNldFZlcnNpb246NTg6UXJTdA==
                predicted_entity:
                  entity_type: DATASET_VERSION
                  id: RGF0YXNldFZlcnNpb246NTg6UXJTdA==
                status: FAILED
                score: null
                comparable_row_count: null
                failed_reason: Scoring failed
    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: One or more fields failed validation.
            instance: /resource/12345
            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
    CreateAlignmentRunRequest:
      description: Body containing alignment run parameters.
      type: object
      required:
        - evaluator_version_id
        - dataset_version_id
        - predicted_entity
      properties:
        evaluator_version_id:
          type: string
          description: |
            The unique identifier for the evaluator version to score. The caller
            must have update access to the evaluator that owns it.
        dataset_version_id:
          type: string
          description: >
            The unique identifier for the dataset version to score over. Must
            belong

            to the alignment task's dataset.
        predicted_entity:
          $ref: '#/components/schemas/AlignmentPredictedEntity'
      additionalProperties: false
    AlignmentRun:
      type: object
      description: >
        One alignment score: how closely an evaluator version's labels matched
        the

        human annotations over one dataset version, using the column pair and

        function its task names. A finished run is never rewritten -- re-scoring

        creates a new run.
      required:
        - id
        - created_at
        - updated_at
        - alignment_task_id
        - evaluator_version_id
        - dataset_version_id
        - predicted_entity
        - status
        - score
        - comparable_row_count
        - failed_reason
      properties:
        id:
          type: string
          description: The unique identifier for the alignment run
        created_at:
          type: string
          format: date-time
          description: When the alignment run was created
        updated_at:
          type: string
          format: date-time
          description: When the alignment run was last modified
        alignment_task_id:
          type: string
          description: >-
            The unique identifier for the alignment task that defined what this
            run compared
        evaluator_version_id:
          type: string
          description: >-
            The unique identifier for the evaluator version whose labels were
            scored
        dataset_version_id:
          type: string
          description: >-
            The unique identifier for the dataset version the comparison ran
            over
        predicted_entity:
          allOf:
            - $ref: '#/components/schemas/AlignmentPredictedEntity'
          nullable: true
          description: >
            The experiment or dataset version that supplied the evaluator
            labels.

            Recorded when the run starts and retained if scoring fails. Null for

            older runs whose prediction source was not recorded.
        status:
          allOf:
            - $ref: '#/components/schemas/TaskRunStatus'
          description: >
            Status of the run. A run that could not be scored is returned with

            `FAILED` and a `failed_reason`; it is still a successfully created
            run,

            not a request error.
        score:
          type: number
          format: double
          nullable: true
          minimum: 0
          maximum: 1
          description: >
            The fraction of comparable rows on which the evaluator's label and
            the

            human annotation agreed, from 0 to 1.


            `null` means no row had both a judge label and a human annotation,
            so

            there was nothing to compare. `null` is not the same as `0`: `0`
            means

            rows were compared and none of them agreed. Treating `null` as `0`

            reports total disagreement where nothing was measured at all.


            Always `null` when `status` is `FAILED`.
        comparable_row_count:
          type: integer
          nullable: true
          minimum: 0
          description: >
            How many rows had both a judge label and a human annotation. This is
            the

            denominator `score` was computed over, so a high `score` over a
            small

            `comparable_row_count` is not meaningful -- read the two together.


            `null` when the count is unknown, which includes every `FAILED` run.
            A

            value of `0` pairs with a `null` `score`.
        failed_reason:
          type: string
          nullable: true
          description: Why the run failed, when `status` is `FAILED`. `null` otherwise.
      additionalProperties: false
      x-forward-compatible: true
    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
      x-forward-compatible: true
    AlignmentPredictedEntity:
      type: object
      description: >-
        The entity whose judge labels are compared against the human
        annotations.
      required:
        - id
        - entity_type
      properties:
        id:
          type: string
          description: >
            The unique identifier for the entity that produced the judge labels

            (base64). An experiment identifier when `entity_type` is
            `EXPERIMENT`, or

            a dataset version identifier when `entity_type` is
            `DATASET_VERSION`.
        entity_type:
          $ref: '#/components/schemas/AlignmentPredictedEntityType'
      additionalProperties: false
    TaskRunStatus:
      type: string
      enum:
        - PENDING
        - RUNNING
        - COMPLETED
        - FAILED
        - CANCELLED
      description: >
        Status of a task run.

        - PENDING - The run has been created but not yet started.

        - RUNNING - The run is currently in progress.

        - COMPLETED - The run finished successfully.

        - FAILED - The run encountered an error and stopped.

        - CANCELLED - The run was cancelled before completion, or it wrote some
        evaluations but hit errors in part of the run.
    AlignmentPredictedEntityType:
      type: string
      enum:
        - EXPERIMENT
        - DATASET_VERSION
      description: >
        What produced the judge labels being scored.

        - EXPERIMENT - An experiment run produced the labels; `id` is an
        experiment identifier.

        - DATASET_VERSION - The labels were already on the dataset; `id` is a
        dataset version identifier.
  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>

        ```

````