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": [],
      "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": [],
      "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": [],
      "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": [],
      "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, 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 span record source: start_time must be before end_time, and the range must not exceed 7 days.
For dataset record source: all example_ids must be non-empty strings.
For project record source:
- span records: all span_ids must be non-empty strings.
- trace records: all trace_ids must be non-empty strings.
At most 500 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"]
    }
  ]
}

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. The record_sources array in the response body will be empty.

POST

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": [],
      "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": [],
      "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": [],
      "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": [],
      "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

Authorization

string

header

required

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

annotation_queue_id

string

required

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

object[]

required

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.

Required array length: 1 - 2 elements

Option 1
Option 2
Option 3

Show child attributes

Response

Returns the created annotation queue records

record_sources

object[]

required

The created annotation queue records

Show child attributes

⌘I

Skills

API reference

API clients

Create annotation queue records

Authorizations

Path Parameters

Body

Response