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

<Note>This endpoint is in beta, read more here.</Note>

{
  "project_id": "proj_abc123",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-08T00:00:00Z",
  "annotations": [
    {
      "values": [
        {
          "name": "accuracy"
        }
      ]
    }
  ]
}