Skip to main content

​
What is Find Moments?

Find Moments turns a plain-language definition of “the thing you care about” into timestamped, structured results. You describe a criterion — instructions plus a JSON schema for the properties each match should carry — and the Find Moments API scans the whole video and returns every span that qualifies. Each moment comes back with start and end times, a title, the reason it qualified, your schema’s properties filled in, and scores for ranking. Unlike Search, which retrieves content similar to a query, Find Moments is exhaustive discovery: a run evaluates the entire video against your criterion and keeps everything that qualifies. Ask for “moments where the customer voices a complaint,” “every pricing discussion,” or “each time the presenter makes a claim about performance,” and you get all of them — not the top few. Find Moments works directly with your files. Under the hood it reads the file’s media description; if a suitable one doesn’t exist yet, one is created automatically as part of the run — you never have to orchestrate describe jobs yourself.

​
Criteria

A criterion is the unit of reuse in Find Moments. It has:
  • name — an identifier for the criterion (e.g. customer_complaint)
  • instructions — plain language describing what qualifies as a moment
  • moment_schema — a JSON schema for the structured properties each moment carries (e.g. { "heat": "high" })
  • scoring (optional) — exactly one scored dimension (key, min, max); the model grades each moment on it
  • finding_schema (optional) — a schema for run-level findings that aren’t tied to a single span, such as “topic X was never covered”
  • anchors (optional) — named timestamps within a moment (e.g. objection_start); required anchors that can’t be located drop the moment, optional ones are simply omitted
Run options control execution: signals_required (which description signals the criterion needs, e.g. speech only), boundary_policy (sentence, tight, loose), speaker_filter, and min/max moment durations.

​
Scores

Each moment can carry up to two scores, and search adds a third — they measure different things: Raw criterion scores are only comparable within one criterion — the API never sorts across criteria by score.

​
Runs are exhaustive; reads are shaped

Every run is a complete pass over the video. “Top-k” is a read-time view, not an execution mode: use limit, min_score, and sort on the GET endpoint to shape what you read back, and change them freely without re-running anything. Repeat requests are cache hits. Submitting the same criterion and options for the same file returns the completed run — and costs nothing. Pass cache_policy: "refresh" to force a fresh run.

​
Findings

When your criterion declares a finding_schema, a run can also return findings — run-level observations validated against that schema. The canonical use is auditing: a talk-track criterion can report { "topic": "speed_to_value", "status": "not_observed" } for a seeded topic the video never covered, something no timestamped moment could express.

​
Working at scale

To run criteria across many videos automatically, use a Moments Collection: attach criteria once, and every file added is processed against all of them, with results queryable across the whole collection via enumeration, structured queries, and moment-scope search.

​
Pricing

A run costs a flat 4 credits. If the file needs a new media description to cover the requested signals, that description is billed at the standard describe rate as part of the run; existing compatible descriptions are reused at no extra cost, and cache-hit runs cost 0.