Bulk Annotate Spans

Submit annotations and notes for multiple observation spans in a single request.

Bulk Annotate Spans

Submit annotations and notes for up to 1,000 observation spans in a single API call. Supports all label types including text, numeric, star, thumbs, and categorical.

POST https://api.futureagi.com/tracer/bulk-annotation/
Bearer 
          Click "Try It" to send a request

Authentication

HeaderDescription
X-Api-KeyYour API key
X-Secret-KeyYour secret key

Request Body

FieldTypeRequiredDescription
recordsarrayYesArray of annotation records (max 1,000)
records[].observation_span_idUUIDYesThe observation span to annotate
records[].annotationsarrayNoAnnotations for this span (max 20 per record)
records[].notesarrayNoNotes for this span (max 20 per record)

Annotation Object

FieldTypeRequiredDescription
annotation_label_idUUIDYesThe annotation label ID
annotator_idUUIDYesThe annotator’s user ID
valuestringConditionalText value (for Text labels)
value_floatfloatConditionalNumeric value (for Numeric/Star labels)
value_boolbooleanConditionalBoolean value (for Thumbs labels)
value_str_listarrayConditionalString array (for Categorical labels)

Value Field Mapping

Label TypeFieldExample
Textvalue"good"
Numericvalue_float4.2
Starvalue_float4.0
Thumbsvalue_booltrue
Categoricalvalue_str_list["option1"]

Note Object

FieldTypeRequiredDescription
textstringYesNote content
annotator_idUUIDYesThe annotator’s user ID

Response

FieldTypeDescription
messagestringSummary message
annotations_createdintegerNew annotations created
annotations_updatedintegerExisting annotations updated
notes_createdintegerNotes created
succeeded_countintegerRecords processed successfully
errors_countintegerRecords that failed
errorsarrayError details for failed records

Code Examples

import requests

resp = requests.post(
    "https://api.futureagi.com/tracer/bulk-annotation/",
    headers={"X-Api-Key": "YOUR_KEY", "X-Secret-Key": "YOUR_SECRET"},
    json={
        "records": [
            {
                "observation_span_id": "span-uuid-1",
                "annotations": [
                    {"annotation_label_id": "label-uuid", "annotator_id": "user-uuid", "value": "good"},
                    {"annotation_label_id": "star-label-uuid", "annotator_id": "user-uuid", "value_float": 4.0}
                ],
                "notes": [{"text": "Accurate output.", "annotator_id": "user-uuid"}]
            },
            {
                "observation_span_id": "span-uuid-2",
                "annotations": [
                    {"annotation_label_id": "thumbs-label-uuid", "annotator_id": "user-uuid", "value_bool": True}
                ]
            }
        ]
    }
)
print(resp.json())
import axios from 'axios';

const resp = await axios.post(
  'https://api.futureagi.com/tracer/bulk-annotation/',
  {
    records: [
      {
        observationSpanId: 'span-uuid-1',
        annotations: [
          { annotationLabelId: 'label-uuid', annotatorId: 'user-uuid', value: 'good' },
          { annotationLabelId: 'star-label-uuid', annotatorId: 'user-uuid', valueFloat: 4.0 }
        ],
        notes: [{ text: 'Accurate output.', annotatorId: 'user-uuid' }]
      },
      {
        observationSpanId: 'span-uuid-2',
        annotations: [
          { annotationLabelId: 'thumbs-label-uuid', annotatorId: 'user-uuid', valueBool: true }
        ]
      }
    ]
  },
  { headers: { 'X-Api-Key': 'YOUR_KEY', 'X-Secret-Key': 'YOUR_SECRET' } }
);
console.log(resp.data);
curl -X POST "https://api.futureagi.com/tracer/bulk-annotation/" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "X-Secret-Key: YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "observation_span_id": "span-uuid-1",
        "annotations": [
          {"annotation_label_id": "label-uuid", "annotator_id": "user-uuid", "value": "good"},
          {"annotation_label_id": "star-label-uuid", "annotator_id": "user-uuid", "value_float": 4.0}
        ],
        "notes": [{"text": "Accurate output.", "annotator_id": "user-uuid"}]
      }
    ]
  }'
Was this page helpful?

Questions & Discussion