> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List alignment runs
> Lists the alignment runs recorded against one alignment task, most recently
created first.
Runs within one task are directly comparable: they share a dataset, a
column pair and a comparison function, so the only thing that varies is
which evaluator version was scored. Scores from *different* tasks are not
comparable with each other -- a different column pair is a different scale.
Use `evaluator_id` to narrow the list to one evaluator's versions, which is
how you see whether that evaluator's agreement with human labels improved as
it was edited. Keep `evaluator_id` identical on every request in a
pagination sequence: a cursor records only a position in the result order,
so pairing one with a different filter silently returns a page of the new
filter's results rather than reporting an error.
Read `score` and `comparable_row_count` together on every run. A `score` of
`null` means no row had both a judge label and a human annotation, which is
not the same as a `score` of `0`; and a `score` over a small
`comparable_row_count` is not a meaningful result. Runs with
`status: FAILED` carry a `null` score and a `failed_reason`.
A task with no runs returns an empty list with `200`. A `404` means the
task does not exist or is not visible to the caller -- the two are
deliberately indistinguishable.
This endpoint is in alpha, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).
## OpenAPI
````yaml https://api.arize.com/v2/spec.yaml get /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:
get:
tags:
- Alignment
summary: List alignment runs
description: >
Lists the alignment runs recorded against one alignment task, most
recently
created first.
Runs within one task are directly comparable: they share a dataset, a
column pair and a comparison function, so the only thing that varies is
which evaluator version was scored. Scores from *different* tasks are
not
comparable with each other -- a different column pair is a different
scale.
Use `evaluator_id` to narrow the list to one evaluator's versions, which
is
how you see whether that evaluator's agreement with human labels
improved as
it was edited. Keep `evaluator_id` identical on every request in a
pagination sequence: a cursor records only a position in the result
order,
so pairing one with a different filter silently returns a page of the
new
filter's results rather than reporting an error.
Read `score` and `comparable_row_count` together on every run. A `score`
of
`null` means no row had both a judge label and a human annotation, which
is
not the same as a `score` of `0`; and a `score` over a small
`comparable_row_count` is not a meaningful result. Runs with
`status: FAILED` carry a `null` score and a `failed_reason`.
A task with no runs returns an empty list with `200`. A `404` means the
task does not exist or is not visible to the caller -- the two are
deliberately indistinguishable.
This endpoint is in alpha, read more
[here](https://arize.com/docs/ax/rest-reference#api-version-stages).
operationId: list_alignment_runs
parameters:
- $ref: '#/components/parameters/AlignmentTaskIdPathParam'
- $ref: '#/components/parameters/EvaluatorIdQueryParam'
- $ref: '#/components/parameters/LimitQueryParam'
- $ref: '#/components/parameters/CursorQueryParam'
responses:
'200':
$ref: '#/components/responses/ListAlignmentRunsResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'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
EvaluatorIdQueryParam:
name: evaluator_id
in: query
required: false
description: >
Limit the results to runs that scored a version of this evaluator. Omit
to
return runs for every evaluator measured against the task.
schema:
$ref: '#/components/schemas/Id'
example: RXZhbHVhdG9yOjEyMzQ1
LimitQueryParam:
name: limit
in: query
description: Maximum items to return. Defaults to 50 if omitted; maximum is 100.
schema:
type: integer
minimum: 1
maximum: 100
default: 50
CursorQueryParam:
name: cursor
in: query
description: |
Opaque pagination cursor returned from a previous response
(`pagination.next_cursor`). Treat it as an unreadable token; do not
attempt to parse or construct it.
schema:
type: string
responses:
ListAlignmentRunsResponse:
description: Returns a list of alignment runs
content:
application/json:
schema:
$ref: '#/components/schemas/ListAlignmentRunsResponse'
examples:
one_page:
summary: Every run for the task fits in one page
value:
alignment_runs:
- 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
- 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
- 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
pagination:
has_more: false
more_pages:
summary: More runs remain; pass next_cursor to read the following page
value:
alignment_runs:
- id: RXZhbEFsaWdubWVudFRhc2tSdW46NDA6YUJjRA==
created_at: '2026-02-14T09:02:11.004Z'
updated_at: '2026-02-14T09:02:13.880Z'
alignment_task_id: T25saW5lVGFzazoxMjphQmNE
evaluator_version_id: RXZhbHVhdG9yVmVyc2lvbjoxMTpYeVp3
dataset_version_id: RGF0YXNldFZlcnNpb246NjA6UXJTdA==
predicted_entity:
entity_type: EXPERIMENT
id: RXhwZXJpbWVudDo5OTpRclN0
status: COMPLETED
score: 0.91
comparable_row_count: 512
failed_reason: null
pagination:
has_more: true
next_cursor: >-
eyJjcmVhdGVkX2F0IjoiMjAyNi0wMi0xNFQwOTowMjoxMS4wMDRaIiwiaWQiOjQwfQ==
empty:
summary: The task has no runs yet
value:
alignment_runs: []
pagination:
has_more: false
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
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
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
ListAlignmentRunsResponse:
type: object
required:
- alignment_runs
- pagination
properties:
alignment_runs:
type: array
items:
$ref: '#/components/schemas/AlignmentRun'
description: A list of alignment runs, most recently created first
pagination:
$ref: '#/components/schemas/PaginationMetadata'
description: Pagination metadata for cursor-based navigation
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
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
PaginationMetadata:
required:
- has_more
type: object
properties:
next_cursor:
type: string
description: >
Opaque cursor for fetching the next page. Treat as an unreadable
token.
Present when `has_more` is true; omitted when `has_more` is false.
has_more:
type: boolean
description: True if another page of results is available.
description: |
Cursor-based pagination metadata. Use `next_cursor` in the subsequent
request's `cursor` query parameter.
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:
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
```
````