Create annotation queue records
curl --request POST \
--url https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"record_sources": [
{
"record_type": "SPAN",
"project_id": "proj_abc123",
"start_time": "2024-01-15T00:00:00Z",
"end_time": "2024-01-15T23:59:59Z",
"span_ids": [
"span_abc123",
"span_def456"
]
}
]
}
'import requests
url = "https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records"
payload = { "record_sources": [
{
"record_type": "SPAN",
"project_id": "proj_abc123",
"start_time": "2024-01-15T00:00:00Z",
"end_time": "2024-01-15T23:59:59Z",
"span_ids": ["span_abc123", "span_def456"]
}
] }
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({
record_sources: [
{
record_type: 'SPAN',
project_id: 'proj_abc123',
start_time: '2024-01-15T00:00:00Z',
end_time: '2024-01-15T23:59:59Z',
span_ids: ['span_abc123', 'span_def456']
}
]
})
};
fetch('https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records', 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/annotation-queues/{annotation_queue_id}/records",
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([
'record_sources' => [
[
'record_type' => 'SPAN',
'project_id' => 'proj_abc123',
'start_time' => '2024-01-15T00:00:00Z',
'end_time' => '2024-01-15T23:59:59Z',
'span_ids' => [
'span_abc123',
'span_def456'
]
]
]
]),
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/annotation-queues/{annotation_queue_id}/records"
payload := strings.NewReader("{\n \"record_sources\": [\n {\n \"record_type\": \"SPAN\",\n \"project_id\": \"proj_abc123\",\n \"start_time\": \"2024-01-15T00:00:00Z\",\n \"end_time\": \"2024-01-15T23:59:59Z\",\n \"span_ids\": [\n \"span_abc123\",\n \"span_def456\"\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/annotation-queues/{annotation_queue_id}/records")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"record_sources\": [\n {\n \"record_type\": \"SPAN\",\n \"project_id\": \"proj_abc123\",\n \"start_time\": \"2024-01-15T00:00:00Z\",\n \"end_time\": \"2024-01-15T23:59:59Z\",\n \"span_ids\": [\n \"span_abc123\",\n \"span_def456\"\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records")
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 \"record_sources\": [\n {\n \"record_type\": \"SPAN\",\n \"project_id\": \"proj_abc123\",\n \"start_time\": \"2024-01-15T00:00:00Z\",\n \"end_time\": \"2024-01-15T23:59:59Z\",\n \"span_ids\": [\n \"span_abc123\",\n \"span_def456\"\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"record_sources": [
{
"id": "aqr_001",
"annotation_queue_id": "aq_abc123",
"source_type": "SPANS",
"data": {
"input": "What is the capital of France?",
"output": "Paris"
},
"annotations": [],
"trace_annotations": [],
"session_annotations": [],
"evaluations": [],
"assigned_users": [
{
"user": {
"id": "usr_123",
"email": "reviewer@example.com"
},
"completion_status": "PENDING"
}
]
},
{
"id": "aqr_002",
"annotation_queue_id": "aq_abc123",
"source_type": "DATASET",
"data": {
"input": "Summarize this article in one sentence.",
"output": "The article discusses climate change impacts."
},
"annotations": [],
"trace_annotations": [],
"session_annotations": [],
"evaluations": [],
"assigned_users": [
{
"user": {
"id": "usr_123",
"email": "reviewer@example.com"
},
"completion_status": "PENDING"
}
]
}
]
}{
"record_sources": [
{
"id": "aqr_001",
"annotation_queue_id": "aq_abc123",
"source_type": "SPANS",
"data": {
"input": "What is the capital of France?",
"output": "Paris"
},
"annotations": [],
"trace_annotations": [],
"session_annotations": [],
"evaluations": [],
"assigned_users": [
{
"user": {
"id": "usr_123",
"email": "reviewer@example.com"
},
"completion_status": "PENDING"
}
]
},
{
"id": "aqr_002",
"annotation_queue_id": "aq_abc123",
"source_type": "DATASET",
"data": {
"input": "Summarize this article in one sentence.",
"output": "The article discusses climate change impacts."
},
"annotations": [],
"trace_annotations": [],
"session_annotations": [],
"evaluations": [],
"assigned_users": [
{
"user": {
"id": "usr_123",
"email": "reviewer@example.com"
},
"completion_status": "PENDING"
}
]
}
]
}{
"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"
}Annotation Queues
Create annotation queue records
Add new records from spans, traces, sessions, or dataset examples to an existing annotation queue.
Payload Requirements
- At least one record source is required.
- At most 2 record sources are allowed per request
- For project record sources:
start_timemust be beforeend_time, and the range must not exceed 7 days. - For dataset record source: all
example_idsmust be non-empty strings. - For project record source:
- span records: all
span_idsmust be non-empty strings. - trace records: all
trace_idsmust be non-empty strings. - session records: all
session_idsmust be non-empty strings.
- span records: all
- At most 500 records total may be added in one request.
- At most 100 session records total may be added in one request.
Valid example (span record)
{
"record_sources": [
{
"record_type": "SPAN",
"project_id": "TW9kZWw6MTIzOmFCY0Q=",
"start_time": "2026-01-15T00:00:00Z",
"end_time": "2026-01-16T00:00:00Z",
"span_ids": ["U3BhbjoxOmFCY0Q="]
}
]
}
Valid example (trace record)
{
"record_sources": [
{
"record_type": "TRACE",
"project_id": "TW9kZWw6MTIzOmFCY0Q=",
"start_time": "2026-01-15T00:00:00Z",
"end_time": "2026-01-16T00:00:00Z",
"trace_ids": ["8fe3373f-0da4-4a8e-b57f-5c8878cfb747"]
}
]
}
Valid example (session record)
{
"record_sources": [
{
"record_type": "SESSION",
"project_id": "TW9kZWw6MTIzOmFCY0Q=",
"start_time": "2026-01-15T00:00:00Z",
"end_time": "2026-01-16T00:00:00Z",
"session_ids": ["session-123"]
}
]
}
Invalid example (span record with start_time after end_time)
{
"record_sources": [
{
"record_type": "SPAN",
"project_id": "TW9kZWw6MTIzOmFCY0Q=",
"start_time": "2026-01-20T00:00:00Z",
"end_time": "2026-01-15T00:00:00Z",
"span_ids": ["U3BhbjoxOmFCY0Q="]
}
]
}
If no example_ids are provided for a dataset record source, all examples in the dataset will be added to the queue only when the total records from all sources does not exceed 500.
Response codes
201 Created: at least one new record was added to the queue.200 OK: the request was valid but all record sources were already present in the queue — no new records were inserted. Therecord_sourcesarray in the response body will be empty.
POST
/
v2
/
annotation-queues
/
{annotation_queue_id}
/
records
Create annotation queue records
curl --request POST \
--url https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"record_sources": [
{
"record_type": "SPAN",
"project_id": "proj_abc123",
"start_time": "2024-01-15T00:00:00Z",
"end_time": "2024-01-15T23:59:59Z",
"span_ids": [
"span_abc123",
"span_def456"
]
}
]
}
'import requests
url = "https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records"
payload = { "record_sources": [
{
"record_type": "SPAN",
"project_id": "proj_abc123",
"start_time": "2024-01-15T00:00:00Z",
"end_time": "2024-01-15T23:59:59Z",
"span_ids": ["span_abc123", "span_def456"]
}
] }
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({
record_sources: [
{
record_type: 'SPAN',
project_id: 'proj_abc123',
start_time: '2024-01-15T00:00:00Z',
end_time: '2024-01-15T23:59:59Z',
span_ids: ['span_abc123', 'span_def456']
}
]
})
};
fetch('https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records', 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/annotation-queues/{annotation_queue_id}/records",
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([
'record_sources' => [
[
'record_type' => 'SPAN',
'project_id' => 'proj_abc123',
'start_time' => '2024-01-15T00:00:00Z',
'end_time' => '2024-01-15T23:59:59Z',
'span_ids' => [
'span_abc123',
'span_def456'
]
]
]
]),
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/annotation-queues/{annotation_queue_id}/records"
payload := strings.NewReader("{\n \"record_sources\": [\n {\n \"record_type\": \"SPAN\",\n \"project_id\": \"proj_abc123\",\n \"start_time\": \"2024-01-15T00:00:00Z\",\n \"end_time\": \"2024-01-15T23:59:59Z\",\n \"span_ids\": [\n \"span_abc123\",\n \"span_def456\"\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/annotation-queues/{annotation_queue_id}/records")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"record_sources\": [\n {\n \"record_type\": \"SPAN\",\n \"project_id\": \"proj_abc123\",\n \"start_time\": \"2024-01-15T00:00:00Z\",\n \"end_time\": \"2024-01-15T23:59:59Z\",\n \"span_ids\": [\n \"span_abc123\",\n \"span_def456\"\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arize.com/v2/annotation-queues/{annotation_queue_id}/records")
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 \"record_sources\": [\n {\n \"record_type\": \"SPAN\",\n \"project_id\": \"proj_abc123\",\n \"start_time\": \"2024-01-15T00:00:00Z\",\n \"end_time\": \"2024-01-15T23:59:59Z\",\n \"span_ids\": [\n \"span_abc123\",\n \"span_def456\"\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"record_sources": [
{
"id": "aqr_001",
"annotation_queue_id": "aq_abc123",
"source_type": "SPANS",
"data": {
"input": "What is the capital of France?",
"output": "Paris"
},
"annotations": [],
"trace_annotations": [],
"session_annotations": [],
"evaluations": [],
"assigned_users": [
{
"user": {
"id": "usr_123",
"email": "reviewer@example.com"
},
"completion_status": "PENDING"
}
]
},
{
"id": "aqr_002",
"annotation_queue_id": "aq_abc123",
"source_type": "DATASET",
"data": {
"input": "Summarize this article in one sentence.",
"output": "The article discusses climate change impacts."
},
"annotations": [],
"trace_annotations": [],
"session_annotations": [],
"evaluations": [],
"assigned_users": [
{
"user": {
"id": "usr_123",
"email": "reviewer@example.com"
},
"completion_status": "PENDING"
}
]
}
]
}{
"record_sources": [
{
"id": "aqr_001",
"annotation_queue_id": "aq_abc123",
"source_type": "SPANS",
"data": {
"input": "What is the capital of France?",
"output": "Paris"
},
"annotations": [],
"trace_annotations": [],
"session_annotations": [],
"evaluations": [],
"assigned_users": [
{
"user": {
"id": "usr_123",
"email": "reviewer@example.com"
},
"completion_status": "PENDING"
}
]
},
{
"id": "aqr_002",
"annotation_queue_id": "aq_abc123",
"source_type": "DATASET",
"data": {
"input": "Summarize this article in one sentence.",
"output": "The article discusses climate change impacts."
},
"annotations": [],
"trace_annotations": [],
"session_annotations": [],
"evaluations": [],
"assigned_users": [
{
"user": {
"id": "usr_123",
"email": "reviewer@example.com"
},
"completion_status": "PENDING"
}
]
}
]
}{
"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 annotation queue identifier (base64) A universally unique identifier (base64-encoded opaque string).
Example:
"RW50aXR5OjEyMzQ1"
Body
application/json
Body containing records to add to an annotation queue
Record sources to add to the annotation queue. At most 2 record sources (projects or datasets) may be provided in a single request. The total number of records resolved from all sources must not exceed 500. The total number of session records across all sources must not exceed 100.
Required array length:
1 - 2 elements- Option 1
- Option 2
- Option 3
- Option 4
Show child attributes
Show child attributes
Response
Returns the created annotation queue records
The created annotation queue records
Show child attributes
Show child attributes
Was this page helpful?