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

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