curl --request POST \
--url https://api.arize.com/v2/datasets/{dataset_id}/examples/annotate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"annotations": [
{
"record_id": "ex_abc",
"values": [
{
"name": "quality",
"score": 0.8
}
]
}
]
}
'import requests
url = "https://api.arize.com/v2/datasets/{dataset_id}/examples/annotate"
payload = { "annotations": [
{
"record_id": "ex_abc",
"values": [
{
"name": "quality",
"score": 0.8
}
]
}
] }
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: 'ex_abc', values: [{name: 'quality', score: 0.8}]}]})
};
fetch('https://api.arize.com/v2/datasets/{dataset_id}/examples/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/datasets/{dataset_id}/examples/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' => 'ex_abc',
'values' => [
[
'name' => 'quality',
'score' => 0.8
]
]
]
]
]),
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/datasets/{dataset_id}/examples/annotate"
payload := strings.NewReader("{\n \"annotations\": [\n {\n \"record_id\": \"ex_abc\",\n \"values\": [\n {\n \"name\": \"quality\",\n \"score\": 0.8\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/datasets/{dataset_id}/examples/annotate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"annotations\": [\n {\n \"record_id\": \"ex_abc\",\n \"values\": [\n {\n \"name\": \"quality\",\n \"score\": 0.8\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arize.com/v2/datasets/{dataset_id}/examples/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\": \"ex_abc\",\n \"values\": [\n {\n \"name\": \"quality\",\n \"score\": 0.8\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 dataset examples
Write human annotations to a batch of examples in a dataset.
Idempotency: Writes use upsert semantics — submitting the same annotation config name for the same example 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
example in the dataset, the annotation for that record is silently ignored.
No error is returned.
Payload Requirements
dataset_idis the path parameter for the target dataset.annotationsis a list of per-example annotation inputs, each identified byrecord_id.- Annotation names must match existing annotation configs in the dataset’s space.
- Up to 1000 examples may be annotated per request.
Valid example
{
"annotations": [
{"record_id": "ex_abc", "values": [{"name": "quality", "score": 0.8}]}
]
}
Invalid example (annotation name not found in space)
{
"annotations": [
{"record_id": "ex_abc", "values": [{"name": "nonexistent_config"}]}
]
}
curl --request POST \
--url https://api.arize.com/v2/datasets/{dataset_id}/examples/annotate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"annotations": [
{
"record_id": "ex_abc",
"values": [
{
"name": "quality",
"score": 0.8
}
]
}
]
}
'import requests
url = "https://api.arize.com/v2/datasets/{dataset_id}/examples/annotate"
payload = { "annotations": [
{
"record_id": "ex_abc",
"values": [
{
"name": "quality",
"score": 0.8
}
]
}
] }
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: 'ex_abc', values: [{name: 'quality', score: 0.8}]}]})
};
fetch('https://api.arize.com/v2/datasets/{dataset_id}/examples/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/datasets/{dataset_id}/examples/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' => 'ex_abc',
'values' => [
[
'name' => 'quality',
'score' => 0.8
]
]
]
]
]),
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/datasets/{dataset_id}/examples/annotate"
payload := strings.NewReader("{\n \"annotations\": [\n {\n \"record_id\": \"ex_abc\",\n \"values\": [\n {\n \"name\": \"quality\",\n \"score\": 0.8\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/datasets/{dataset_id}/examples/annotate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"annotations\": [\n {\n \"record_id\": \"ex_abc\",\n \"values\": [\n {\n \"name\": \"quality\",\n \"score\": 0.8\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arize.com/v2/datasets/{dataset_id}/examples/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\": \"ex_abc\",\n \"values\": [\n {\n \"name\": \"quality\",\n \"score\": 0.8\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
Path Parameters
The unique dataset identifier (base64) A universally unique identifier (base64-encoded opaque string).
"RW50aXR5OjEyMzQ1"
Body
Body containing dataset example annotation batch
Batch annotation request for dataset examples.
Batch of dataset example annotations to write. Up to 1000 examples per request.
1 - 1000 elementsShow child attributes
Show child attributes
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?