Annotate a batch of project spans

curl --request POST \
  --url https://api.arize.com/v2/spans/annotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_id": "proj_abc123",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-08T00:00:00Z",
  "annotations": [
    {
      "record_id": "span_abc",
      "values": [
        {
          "name": "relevance",
          "label": "good",
          "score": 0.9
        }
      ]
    }
  ]
}
'

import requests

url = "https://api.arize.com/v2/spans/annotate"

payload = {
    "project_id": "proj_abc123",
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-08T00:00:00Z",
    "annotations": [
        {
            "record_id": "span_abc",
            "values": [
                {
                    "name": "relevance",
                    "label": "good",
                    "score": 0.9
                }
            ]
        }
    ]
}
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({
    project_id: 'proj_abc123',
    start_time: '2024-01-01T00:00:00Z',
    end_time: '2024-01-08T00:00:00Z',
    annotations: [
      {
        record_id: 'span_abc',
        values: [{name: 'relevance', label: 'good', score: 0.9}]
      }
    ]
  })
};

fetch('https://api.arize.com/v2/spans/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/spans/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([
    'project_id' => 'proj_abc123',
    'start_time' => '2024-01-01T00:00:00Z',
    'end_time' => '2024-01-08T00:00:00Z',
    'annotations' => [
        [
                'record_id' => 'span_abc',
                'values' => [
                                [
                                                                'name' => 'relevance',
                                                                'label' => 'good',
                                                                'score' => 0.9
                                ]
                ]
        ]
    ]
  ]),
  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/spans/annotate"

	payload := strings.NewReader("{\n  \"project_id\": \"proj_abc123\",\n  \"start_time\": \"2024-01-01T00:00:00Z\",\n  \"end_time\": \"2024-01-08T00:00:00Z\",\n  \"annotations\": [\n    {\n      \"record_id\": \"span_abc\",\n      \"values\": [\n        {\n          \"name\": \"relevance\",\n          \"label\": \"good\",\n          \"score\": 0.9\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/spans/annotate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"project_id\": \"proj_abc123\",\n  \"start_time\": \"2024-01-01T00:00:00Z\",\n  \"end_time\": \"2024-01-08T00:00:00Z\",\n  \"annotations\": [\n    {\n      \"record_id\": \"span_abc\",\n      \"values\": [\n        {\n          \"name\": \"relevance\",\n          \"label\": \"good\",\n          \"score\": 0.9\n        }\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arize.com/v2/spans/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  \"project_id\": \"proj_abc123\",\n  \"start_time\": \"2024-01-01T00:00:00Z\",\n  \"end_time\": \"2024-01-08T00:00:00Z\",\n  \"annotations\": [\n    {\n      \"record_id\": \"span_abc\",\n      \"values\": [\n        {\n          \"name\": \"relevance\",\n          \"label\": \"good\",\n          \"score\": 0.9\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"
}

Spans

Annotate a batch of project spans

Write human annotations to a batch of spans in a project.

Idempotency: Writes use upsert semantics — submitting the same annotation config name for the same span 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.

Partial failure: Writes are grouped by calendar day and processed sequentially. A non-2xx response means the request failed during the write phase — annotations for earlier calendar-day buckets may already be saved while later ones are not. It is safe to retry the full request; re-submitting a record that was already saved will overwrite it with the same value (no duplicates).

Payload Requirements

project_id is required and must identify a project the caller has span annotation access to.
annotations is a list of per-span annotation inputs. Each entry identifies one span by its record_id and provides one or more annotation values.
Each record_id must be unique within the request (duplicates return 400).
Each record’s values list must not contain duplicate annotation config names (returns 400).
start_time / end_time constrain the time range for span lookup. If omitted, start_time defaults to 31 days ago and end_time to now. Both start_time and end_time may not be in the future. The window may not exceed 31 days. If ANY span ID cannot be located within the given range, the entire request is rejected with 404 and no annotations are written (all-or-nothing pre-validation). Only after all spans are confirmed does the write phase begin.
Annotation names must match existing annotation configs in the project’s space.
Up to 1000 span records may be annotated per request.

Valid example

{
  "project_id": "proj_abc123",
  "annotations": [
    {"record_id": "span_abc", "values": [{"name": "relevance", "label": "good", "score": 1.0}]}
  ]
}

Invalid example (annotation name not found in space)

{
  "project_id": "proj_abc123",
  "annotations": [
    {"record_id": "span_abc", "values": [{"name": "nonexistent_config"}]}
  ]
}

Invalid example (time window exceeds 31 days)

{
  "project_id": "proj_abc123",
  "start_time": "2025-01-01T00:00:00Z",
  "end_time": "2025-03-01T00:00:00Z",
  "annotations": [
    {"record_id": "span_abc", "values": [{"name": "relevance", "label": "good"}]}
  ]
}

This endpoint is in beta, read more here.

POST

spans

annotate

Annotate a batch of project spans

curl --request POST \
  --url https://api.arize.com/v2/spans/annotate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_id": "proj_abc123",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-08T00:00:00Z",
  "annotations": [
    {
      "record_id": "span_abc",
      "values": [
        {
          "name": "relevance",
          "label": "good",
          "score": 0.9
        }
      ]
    }
  ]
}
'

import requests

url = "https://api.arize.com/v2/spans/annotate"

payload = {
    "project_id": "proj_abc123",
    "start_time": "2024-01-01T00:00:00Z",
    "end_time": "2024-01-08T00:00:00Z",
    "annotations": [
        {
            "record_id": "span_abc",
            "values": [
                {
                    "name": "relevance",
                    "label": "good",
                    "score": 0.9
                }
            ]
        }
    ]
}
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({
    project_id: 'proj_abc123',
    start_time: '2024-01-01T00:00:00Z',
    end_time: '2024-01-08T00:00:00Z',
    annotations: [
      {
        record_id: 'span_abc',
        values: [{name: 'relevance', label: 'good', score: 0.9}]
      }
    ]
  })
};

fetch('https://api.arize.com/v2/spans/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/spans/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([
    'project_id' => 'proj_abc123',
    'start_time' => '2024-01-01T00:00:00Z',
    'end_time' => '2024-01-08T00:00:00Z',
    'annotations' => [
        [
                'record_id' => 'span_abc',
                'values' => [
                                [
                                                                'name' => 'relevance',
                                                                'label' => 'good',
                                                                'score' => 0.9
                                ]
                ]
        ]
    ]
  ]),
  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/spans/annotate"

	payload := strings.NewReader("{\n  \"project_id\": \"proj_abc123\",\n  \"start_time\": \"2024-01-01T00:00:00Z\",\n  \"end_time\": \"2024-01-08T00:00:00Z\",\n  \"annotations\": [\n    {\n      \"record_id\": \"span_abc\",\n      \"values\": [\n        {\n          \"name\": \"relevance\",\n          \"label\": \"good\",\n          \"score\": 0.9\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/spans/annotate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"project_id\": \"proj_abc123\",\n  \"start_time\": \"2024-01-01T00:00:00Z\",\n  \"end_time\": \"2024-01-08T00:00:00Z\",\n  \"annotations\": [\n    {\n      \"record_id\": \"span_abc\",\n      \"values\": [\n        {\n          \"name\": \"relevance\",\n          \"label\": \"good\",\n          \"score\": 0.9\n        }\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arize.com/v2/spans/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  \"project_id\": \"proj_abc123\",\n  \"start_time\": \"2024-01-01T00:00:00Z\",\n  \"end_time\": \"2024-01-08T00:00:00Z\",\n  \"annotations\": [\n    {\n      \"record_id\": \"span_abc\",\n      \"values\": [\n        {\n          \"name\": \"relevance\",\n          \"label\": \"good\",\n          \"score\": 0.9\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

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

Body

application/json

Body containing span annotation batch

Batch annotation request for project spans.

project_id

string

required

The project (model) ID whose spans are being annotated.

Example:

"proj_abc123"

annotations

object[]

required

Batch of span annotations to write. Up to 1000 spans per request.

Required array length: 1 - 1000 elements

Show child attributes

start_time

string<date-time>

Start of the time range for span lookup. Optional; defaults to 31 days ago.

Example:

"2024-01-01T00:00:00Z"

end_time

string<date-time>

End of the time range for span lookup. Optional; defaults to now.

Example:

"2024-01-08T00:00:00Z"

granularity

enum<string>

default:SPAN

Whether the record is a span or a trace, which affects whether annotations are written as span annotations or trace annotations. Attempts to write trace annotations on spans will be rejected. Optional; defaults to 'SPAN'.

Available options:

SPAN,

TRACE

Response

Annotations accepted. Writes are idempotent; retry on failure is safe.

⌘I

API reference

API clients

Annotate a batch of project spans

Authorizations

Body

Response