> ## 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.

# Moments Collections

> Run moment criteria across a whole video library automatically, then enumerate, query, and search the results

## What are Moments Collections?

A Moments Collection applies [Find Moments](/core-concepts/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.

```json theme={null}
POST /v1/collections
{
  "collection_type": "moments",
  "name": "sales-call-moments",
  "moments_config": {
    "criteria": [
      {
        "criterion": {
          "name": "customer_complaint",
          "instructions": "Find moments where the customer voices a complaint or pain point.",
          "moment_schema": {
            "type": "object",
            "properties": { "heat": { "type": "string", "enum": ["low", "medium", "high"] } },
            "required": ["heat"]
          },
          "scoring": { "key": "complaint_strength", "min": 1, "max": 10 }
        },
        "signals_required": ["speech"]
      }
    ]
  }
}
```

## Managing criteria

Criteria are mutable after creation:

* [Attach a criterion](/api-reference/endpoint/collections/moment-criteria-post) — 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](/api-reference/endpoint/collections/moment-criteria-delete) — 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](/api-reference/endpoint/collections/list-collection-moments) and [List Collection Moment Findings](/api-reference/endpoint/collections/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](/deep-dives/structured-queries) 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](/deep-dives/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.