Bulk Annotate Spans — API

Submit label scores and notes for multiple observation spans in one request. Accepts an array of span IDs with their annotation values and score sources.

POST https://api.futureagi.com/tracer/bulk-annotation/

Authentication

X-Api-Key API Key Required

Your Future AGI API key used to authenticate requests. You can find and manage your API keys in the Dashboard under Settings.

X-Secret-Key Secret Key Required

Your Future AGI secret key, used alongside the API key for request authentication. This is generated when you create an API key in the Dashboard.

Request body

records array of objects Required

Array of annotation records (max 1,000).

observation_span_id UUID Required

The observation span to annotate.

annotations array of objects

Annotations for this span (max 20 per record). Each object contains annotation_label_id (UUID, required) and exactly one value field: value (string, for text labels), value_float (number, for numeric and star labels), value_bool (boolean, for thumbs_up_down labels), or value_str_list (array of strings, for categorical labels).

notes array of objects

Notes for this span (max 20 per record). Each object contains text (string, max 5,000 characters).

Response

200 OK
message string
Always "Bulk annotation completed".
annotations_created integer
Number of new annotations created.
annotations_updated integer
Number of existing annotations updated.
notes_created integer
Number of notes created.
succeeded_count integer
Total of created + updated + notes.
errors_count integer
Number of records that failed.
warnings_count integer
Number of warnings (e.g. existing annotations updated).
warnings array Optional
Present when warnings occurred. Each entry has record_index, span_id, label_id, warning.
errors array Optional
Present when errors occurred. Each entry has record_index, span_id, and an error message field.

Errors

400 Bad Request Optional

Invalid request parameters.

401 Unauthorized Optional

Invalid or missing API credentials.

500 Internal Server Error Optional

Unexpected server error.

Note

Authentication uses the API key — the annotator identity is always the authenticated user. The annotator_id field is not accepted per annotation; the system uses the authenticated user for all annotations in the request.

Provide exactly one value field per annotation (value, value_float, value_bool, or value_str_list) matching the label type. Providing the wrong field or multiple value fields returns a per-record error.

GET /
Authentication
REQUEST 
 
 
  
 
 RESPONSE