> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudglue.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Find Moments

> Find every moment in a video that matches a criterion you define — with structured properties, scores, and findings

## 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](/api-reference/endpoint/find-moments/post) 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](/core-concepts/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](/core-concepts/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:

| Score             | Where            | Meaning                                                          |
| ----------------- | ---------------- | ---------------------------------------------------------------- |
| `criterion_score` | Moment           | The grade on your declared scoring dimension, on your scale      |
| `rank_score`      | Moment           | Normalized 0–1 ordering within a run; what the default sort uses |
| `search_score`    | Search hits only | Query relevance for one search; unrelated to the two above       |

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](/api-reference/endpoint/find-moments/get) 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](/core-concepts/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](/deep-dives/structured-queries), and moment-scope [search](/core-concepts/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**.