Orchestrate bulk video and audio analysis safely

A saved scanner gives every video or audio recording the same versioned contract. The durable batch API accepts explicit work, retains item state, and lets you aggregate observations without losing modality or provenance.

Recommended queue

1. Enumerate authorized recordings in your system.
2. Create and complete one account-owned private video or audio upload per recording.
3. Group 1–100 scanner/upload pairs into a POST /v1/scanner-batches request with a stable idempotency key and unique client_id values.
4. Stay within the concurrency and monthly-minute limits shown in Usage; every item is an independent run and charge.
5. Treat batch queued as accepted and waiting fairly. Underlying runs may be queued, dispatched, or processing; none guarantees an immediate start.
6. Page through batch items, poll active runs every 5–10 seconds with jitter, or use signed completion webhooks when enabled for your account.
7. Fetch observations only after completion and store batch, item, run, scanner-version, media-kind, and evidence-kind fields.

POST /v1/scanner-batches
Idempotency-Key: replay-cohort-2026-08-15-page-1
{"items": [
  {"client_id":"rec-1842:v3",
   "scanner_id":"scn_...",
   "upload_id":"upl_...",
   "metadata":{"recording_id":"rec_1842","cohort":"new-user"}}
]}

Do not erase zero-result runs

A completed run with zero observations is unanswerable from the available visual or audio evidence. Keep it distinct from failed or unprocessed work—and from an answered monitor no-match, which contains one explicit full-source boolean false observation.

Preserve the public result contract

Store the scanner version, timestamps, value, and source metadata with each result. Video find_moments observations include Moment IDs for explicit rendering. Audio-only findings remain JSON-only, and generated speech excerpts are not certified verbatim transcripts.

Aggregate typed values carefully

Group only compatible semantics and scanner versions. A classifier label, a numeric scorer value, and a timestamped moment answer different questions. Relevance can order candidates inside a workflow but should not be presented as a calibrated confidence percentage.

Retry and cancel without duplicate work

Use a deterministic idempotency key for batch creation. Preserve the returned batch and item IDs before submitting more work, apply exponential backoff to transient failures, and stop retrying validation or authorization errors until the request changes. POST /v1/scanner-batches/{batch_id}/cancel stops queued items from starting; already-spawned items drain instead of being claimed as instantly canceled.