---
title: "Annotate a batch of experiment runs"
method: POST
path: "/v2/experiments/{experiment_id}/runs/annotate"
tags: ["Experiments"]
---

# Annotate a batch of experiment runs

`POST /v2/experiments/{experiment_id}/runs/annotate`

Write human annotations to a batch of runs in an experiment.

**Idempotency**: Writes use upsert semantics — submitting the same annotation
config name for the same run 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. No response body
is returned.

**Unmatched record IDs**: If a `record_id` does not correspond to an existing
run in the experiment, the annotation for that record is silently ignored.
No error is returned.

**Payload Requirements**
- `experiment_id` is the path parameter for the target experiment.
- `annotations` is a list of per-run annotation inputs, each identified by `record_id`.
- Annotation names must match existing annotation configs in the experiment's space.
- Up to 1000 runs may be annotated per request.

**Valid example**
```json
{
  "annotations": [
    {"record_id": "run_abc", "values": [{"name": "quality", "label": "good"}]}
  ]
}
```

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

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

## Path parameters

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

## Request body

- AnnotateExperimentRunsRequest — Batch annotation request for experiment runs.
  - `annotations` AnnotateRecordInput[], required — Batch of experiment run annotations to write. Up to 1000 runs per request.
    - `record_id` string, required — The record identifier (span ID, dataset example ID, or experiment run ID, depending on the endpoint).
    - `values` AnnotationInput[], required — One or more annotation values to set on this record.
      - `name` string, required — The annotation config name
      - `score` number, double — Numeric score for the annotation. Omit to leave unchanged.
      - `label` string — Categorical label for the annotation. Omit to leave unchanged.
      - `text` string — Free-form text note for the annotation. Omit to leave unchanged.

## Response `202`

Annotations written successfully.
The annotations have been accepted and will be written. Visibility in read queries may lag by a short interval.

## Other responses

- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `422` — Unprocessable entity
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/versions/2ce448f1de13/schema)