Skip to main content

​
What are Moments Collections?

A Moments Collection applies Find Moments criteria across every video in the collection. Create it with collection_type: "moments" and one or more criteria in moments_config; from then on, each file you add is processed against all attached criteria automatically — one run per (file, criterion) pair. The result is a standing, queryable dataset of moments across your library: every complaint in a quarter of sales calls, every safety violation across inspection footage, every claim in a season of episodes.

​
Managing criteria

Criteria are mutable after creation:
  • Attach a criterion — starts a backfill over the collection’s existing members; the attachment’s backfill_status and files_total / files_completed / files_failed counters track progress (echoed live on the single-collection GET).
  • Detach a criterion — stops future processing. Completed runs and their moments persist as account history: they remain visible on their own run endpoints, in account-scoped search, and in the query tables.
Runs are shared with the on-demand API: if a file already has a completed run for an identical criterion and options, the collection reuses it instead of paying for a new one.

​
Reading results

  • Enumeration: List Collection Moments and List Collection Moment Findings return records with provenance (file_id, job_id, criterion_name) and cursor pagination. The default sort is positional (by file, then start time); score sorts require narrowing to a single criterion, because raw criterion scores are never comparable across criteria.
  • Structured queries: the Query API exposes moments, moment_findings, and moment_collection_links virtual tables for SQL and natural-language questions (“which rep drew the most high-heat complaints?”).
  • Search: POST /v1/search with scope: "moment" runs semantic search over the collection’s moments, optionally narrowed by criterion_name. Hits carry the full moment record plus a search_score (query relevance — distinct from criterion_score and rank_score).
  • Agent: the Responses API can answer moments questions over these collections through its SQL tool with no extra setup.

​
Pricing

Adding a file is billed upfront per attached criterion: 4 credits per (file, criterion) run, plus one standard describe charge if the file needs a new media description (one description covers all criteria — the collection creates a single description spanning every criterion’s required signals). Attaching a criterion later bills each backfill run the same way as it executes. Reused runs and reused descriptions cost nothing.