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).
• granularity selects what record_id identifies: SPAN (a span ID, the default), TRACE (a trace’s root span ID), or SESSION (a session ID). For SESSION, the annotation is written to the root span of the session’s earliest trace found within the lookup window.
• start_time / end_time constrain the time range for span lookup. If omitted, start_time defaults to 31 days before end_time (7 days for SESSION granularity) and end_time to now. Both start_time and end_time may not be in the future. For SPAN/TRACE the window may not exceed 31 days; for SESSION it may not exceed 7 days. If ANY span 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 records may be annotated per request for SPAN/TRACE granularity; up to 100 records per request for SESSION granularity.

Valid example

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

Valid example (session granularity)

{
  "project_id": "proj_abc123",
  "granularity": "SESSION",
  "annotations": [
    {"record_id": "session_abc", "values": [{"name": "quality", "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"}]}
  ]
}

Invalid example (session time window exceeds 7 days)

{
  "project_id": "proj_abc123",
  "granularity": "SESSION",
  "start_time": "2025-01-01T00:00:00Z",
  "end_time": "2025-01-15T00:00:00Z",
  "annotations": [
    {"record_id": "session_abc", "values": [{"name": "quality", "label": "good"}]}
  ]
}

This endpoint is in beta, read more here.

POST /v2/spans/annotate

Annotate a batch of project spans

cURL

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
        }
      ]
    }
  ]
}
'

400

{
  "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"
}

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 annotations to write. Up to 1000 records per request for SPAN or TRACE granularity; up to 100 records per request for SESSION granularity.

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 before end_time, or 7 days before end_time when granularity is SESSION.

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, a trace, or a session, which affects whether annotations are written as span, trace, or session annotations. For TRACE, each record_id must be a trace's root span; attempts to write trace annotations on non-root spans will be rejected. For SESSION, each record_id is a session ID; the annotation is written to the root span of the session's earliest trace within the lookup window. Optional; defaults to 'SPAN'.

Available options: SPAN, TRACE, SESSION

Response

202

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