Batch Runs & Ground Truth

Run the pipeline over many videos

One run per video, processed as bulk work so it does not slow down interactive requests. Pick videos with videoIds, or with a selector (source_id, from, to, tag; up to 5,000 videos). Videos that already have a run are skipped unless force is true. Returns 202 with a batch_id. Runs are charged in tokens at the batch rate. Returns 429 with code: "bulk_ceiling" when the project already has too much bulk work waiting. Requires write access.

curl -X POST https://platform.endlessai.com/api/v1/projects/PROJECT_ID/pipeline/trigger-batch \
    -H "X-Api-Key: YOUR_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "selector": { "source_id": "src_SOURCE_ID", "from": "2026-10-01T00:00:00Z", "to": "2026-10-02T00:00:00Z" },
      "deadline": "2026-10-02T06:00:00Z"
    }'

import requests

  resp = requests.post(
      f"{BASE}/projects/{PROJECT_ID}/pipeline/trigger-batch",
      headers={"X-Api-Key": API_KEY},
      json={
          "selector": {
              "source_id": "src_SOURCE_ID",
              "from": "2026-10-01T00:00:00Z",
              "to": "2026-10-02T00:00:00Z",
          },
          "deadline": "2026-10-02T06:00:00Z",
      },
  )
  batch_id = resp.json()["batch_id"]

const res = await fetch(
    `${BASE}/projects/${projectId}/pipeline/trigger-batch`,
    {
      method: "POST",
      headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
      body: JSON.stringify({
        selector: {
          source_id: "src_SOURCE_ID",
          from: "2026-10-01T00:00:00Z",
          to: "2026-10-02T00:00:00Z",
        },
        deadline: "2026-10-02T06:00:00Z",
      }),
    }
  );
  const { batch_id } = await res.json();

// Response (202)
  {
    "batch_id": "batch_BATCH_ID",
    "enqueued": 214,
    "requested": 214,
    "progress_url": "/api/v1/projects/PROJECT_ID/batches/batch_BATCH_ID"
  }

Get batch progress

overdue is true when the batch's deadline has passed and runs are still outstanding.

{
    "id": "batch_BATCH_ID",
    "item_count": 214,
    "deadline": "2026-10-02T06:00:00Z",
    "created_at": "2026-10-01T22:00:00Z",
    "counts": { "queued": 40, "running": 4, "completed": 168, "failed": 2 },
    "done": 170,
    "total": 214,
    "overdue": false
  }

Record the correct label for a run

Use the run_id from the video's agent report. One label per run and origin (external_system by default, or human_review); posting again replaces it. Requires write access.

{ "label": "class_2", "origin": "human_review", "annotator": "reviewer@example.com" }

Record correct labels in bulk

Up to 1,000 items keyed by your own external_id (the id stored on the video when it was ingested). Each label is attached to the latest finished run for that id; each result says ok or gives an error such as no run found. Requires write access.

{
    "items": [
      { "external_id": "txn-88213", "label": "class_2" },
      { "external_id": "txn-88214", "label": "class_3" }
    ]
  }

Get label accuracy

Compares the labels runs produced with the correct labels you recorded. Filter with from, to and source_id. accuracy is null when nothing matches.

{
    "total": 170,
    "correct": 161,
    "accuracy": 0.947,
    "per_label": {
      "class_2": { "total": 120, "correct": 116, "accuracy": 0.967 },
      "class_3": { "total": 50, "correct": 45, "accuracy": 0.9 }
    },
    "confusions": [{ "truth": "class_3", "predicted": "class_2", "n": 5 }]
  }