A saved scanner gives every recording the same versioned contract. Bulk processing is then an orchestration problem: submit bounded work, retain IDs, poll responsibly, and aggregate observations without losing provenance.
Recommended queue
- Enumerate authorized recordings in your system.
- Create and complete one account-owned private upload per recording.
- Create one independently billed run per scanner and upload with a stable idempotency key.
- Stay within the concurrency and monthly-minute limits shown in Usage.
- Poll active runs every 5–10 seconds with jitter, or use signed completion webhooks when enabled for your account.
- Fetch observations only after completion and store the run and scanner-version IDs.
for recording in recordings:
POST /v1/scanners/scn_.../runs
Idempotency-Key: replay:{recording.id}:scanner:v3
{"upload_id": recording.upload_id,
"metadata": {"recording_id": recording.id, "cohort": recording.cohort}}Do not erase zero-result runs
A completed run with zero observations is an unanswerable visual result. Keep it distinct from failed or unprocessed work—and from an answered monitor no-match, which contains one explicit boolean false observation.
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 without duplicate work
Use deterministic idempotency keys for run creation. Preserve the returned run ID before submitting more work, apply exponential backoff to transient failures, and stop retrying validation or authorization errors until the request changes.