curl --request POST \
--url https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"annotations": [
{
"record_id": "run_abc",
"values": [
{
"name": "quality",
"label": "good"
}
]
}
]
}
'import requests
url = "https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate"
payload = { "annotations": [
{
"record_id": "run_abc",
"values": [
{
"name": "quality",
"label": "good"
}
]
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
annotations: [{record_id: 'run_abc', values: [{name: 'quality', label: 'good'}]}]
})
};
fetch('https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'annotations' => [
[
'record_id' => 'run_abc',
'values' => [
[
'name' => 'quality',
'label' => 'good'
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate"
payload := strings.NewReader("{\n \"annotations\": [\n {\n \"record_id\": \"run_abc\",\n \"values\": [\n {\n \"name\": \"quality\",\n \"label\": \"good\"\n }\n ]\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"annotations\": [\n {\n \"record_id\": \"run_abc\",\n \"values\": [\n {\n \"name\": \"quality\",\n \"label\": \"good\"\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"annotations\": [\n {\n \"record_id\": \"run_abc\",\n \"values\": [\n {\n \"name\": \"quality\",\n \"label\": \"good\"\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}Annotate a batch of experiment runs
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_idis the path parameter for the target experiment.annotationsis a list of per-run annotation inputs, each identified byrecord_id.- Annotation names must match existing annotation configs in the experiment’s space.
- Up to 1000 runs may be annotated per request.
Valid example
{
"annotations": [
{"record_id": "run_abc", "values": [{"name": "quality", "label": "good"}]}
]
}
Invalid example (annotation name not found in space)
{
"annotations": [
{"record_id": "run_abc", "values": [{"name": "nonexistent_config"}]}
]
}
curl --request POST \
--url https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"annotations": [
{
"record_id": "run_abc",
"values": [
{
"name": "quality",
"label": "good"
}
]
}
]
}
'import requests
url = "https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate"
payload = { "annotations": [
{
"record_id": "run_abc",
"values": [
{
"name": "quality",
"label": "good"
}
]
}
] }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
annotations: [{record_id: 'run_abc', values: [{name: 'quality', label: 'good'}]}]
})
};
fetch('https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'annotations' => [
[
'record_id' => 'run_abc',
'values' => [
[
'name' => 'quality',
'label' => 'good'
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate"
payload := strings.NewReader("{\n \"annotations\": [\n {\n \"record_id\": \"run_abc\",\n \"values\": [\n {\n \"name\": \"quality\",\n \"label\": \"good\"\n }\n ]\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"annotations\": [\n {\n \"record_id\": \"run_abc\",\n \"values\": [\n {\n \"name\": \"quality\",\n \"label\": \"good\"\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arize.com/v2/experiments/{experiment_id}/runs/annotate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"annotations\": [\n {\n \"record_id\": \"run_abc\",\n \"values\": [\n {\n \"name\": \"quality\",\n \"label\": \"good\"\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}{
"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"
}Authorizations
Most Arize AI endpoints require authentication. For those endpoints that require authentication, include your API key in the request header using the format
Service accounts may instead present an access token issued by an external identity provider (Microsoft Entra ID) when the account admin has configured that provider. Send it in the same header: Authorization: Bearer <access-token>.
Path Parameters
Body
Body containing experiment run annotation batch
Response
Annotations written successfully. The annotations have been accepted and will be written. Visibility in read queries may lag by a short interval.
Was this page helpful?