---
title: "Find moments in a video"
method: POST
path: "/find-moments"
tags: ["Find Moments"]
---

# Find moments in a video

`POST /find-moments`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/find-moments`
- Auth: HTTP bearer

Runs exhaustive moment discovery for one criterion over one video. Every accepted moment is persisted; ranking and truncation are read-time parameters on GET. Reuses a compatible describe or creates one internally - a missing describe is never an error.

## Request body

- NewFindMoments
  - `url` string, required: cloudglue://files/<id> or an ingestible URL (same resolution rules as describe/extract).
  - `describe_job_id` string, uuid: Optional pin to a specific describe. It must exist for the file and its config must cover signals_required.
  - `criterion` MomentCriterion, required: An inline criterion: rubric instructions plus typed output declarations. Snapshotted and hashed onto the run.
    - `name` string, required
    - `instructions` string, required: The complete rubric, including any seed lists and worked examples.
    - `moment_schema` MomentSchemaDefinition: A validated JSON Schema subset (the moment schema dialect): a root object of string/number/integer/boolean/array-of-those fields, optional enums, one nesting level, per-field descriptions. Rejected shapes get a field-addressable 400 with a stable code.
    - `finding_schema` MomentSchemaDefinition: A validated JSON Schema subset (the moment schema dialect): a root object of string/number/integer/boolean/array-of-those fields, optional enums, one nesting level, per-field descriptions. Rejected shapes get a field-addressable 400 with a stable code.
    - `anchors` object: Named intra-moment timestamps. A non-required anchor that does not exist is omitted from the moment - never null.
    - `scoring` object: The rubric's single canonical score: what rank-ordered reads sort by and what min_score filters on. Exactly one scoring key per criterion.
      - `key` string, required
      - `min` number, required
      - `max` number, required
      - `higher_is_better` boolean
      - `description` string
  - `signals_required` string[]
  - `boundary_policy` 'sentence' | 'tight' | 'loose'
  - `speaker_filter` object
    - `include` string[]
    - `exclude` string[]
    - `match` 'any' | 'all'
  - `min_duration_seconds` number
  - `max_duration_seconds` number
  - `cache_policy` 'reuse' | 'refresh'

## Response `200`

The created run, or an existing matching run at cost 0 (cache hit).

- FindMoments
  - `job_id` string, uuid, required
  - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled', required
  - `created_at` integer, required: Unix timestamp in milliseconds when the run was created
  - `url` string, required
  - `find_moments_config` object: Echo of the request as the run resolved it, plus criterion_hash, the resolved describe_job_id, and the engine version. Defaults the request omitted are filled in here.
    - `criterion` MomentCriterion: An inline criterion: rubric instructions plus typed output declarations. Snapshotted and hashed onto the run.
      - `name` string, required
      - `instructions` string, required: The complete rubric, including any seed lists and worked examples.
      - `moment_schema` MomentSchemaDefinition: A validated JSON Schema subset (the moment schema dialect): a root object of string/number/integer/boolean/array-of-those fields, optional enums, one nesting level, per-field descriptions. Rejected shapes get a field-addressable 400 with a stable code.
      - `finding_schema` MomentSchemaDefinition: A validated JSON Schema subset (the moment schema dialect): a root object of string/number/integer/boolean/array-of-those fields, optional enums, one nesting level, per-field descriptions. Rejected shapes get a field-addressable 400 with a stable code.
      - `anchors` object: Named intra-moment timestamps. A non-required anchor that does not exist is omitted from the moment - never null.
      - `scoring` object: The rubric's single canonical score: what rank-ordered reads sort by and what min_score filters on. Exactly one scoring key per criterion.
        - `key` string, required
        - `min` number, required
        - `max` number, required
        - `higher_is_better` boolean
        - `description` string
    - `criterion_hash` string: Stable hash of the snapshotted criterion; identical criteria share a hash.
    - `describe_job_id` string, uuid: The describe the run actually used, whether reused, pinned, or created internally.
    - `signals_required` string[]
    - `boundary_policy` 'sentence' | 'tight' | 'loose'
    - `speaker_filter` object: Speaker restriction, present when the request set one.
    - `min_duration_seconds` number
    - `max_duration_seconds` number
    - `cache_policy` 'reuse' | 'refresh'
    - `engine_version` integer: Version of the moment-discovery engine that produced the run.
  - `moments` Moment[]
    - `moment_id` string, uuid, required
    - `start_time` number, required: Seconds from source start.
    - `end_time` number, required
    - `anchors` object: Declared anchors only; an anchor that was not found is absent, never null.
    - `title` string, required
    - `reason` string, required
    - `speakers` string[]
    - `criterion_score` CriterionScore: The rubric's judgment on its own declared scale.
      - `key` string, required
      - `value` number, required
      - `min` number, required
      - `max` number, required
    - `rank_score` number, required: Normalized ordering within the run; what the default sort uses.
    - `properties` object: Validates against the criterion's moment_schema.
    - `evidence` object
      - `signals` string[]
  - `findings` MomentFinding[]
    - `finding_id` string, uuid, required
    - `kind` 'absence' | 'observation', required
    - `properties` object, required: Validates against the criterion's finding_schema.
  - `total_moments` integer: Full accepted count, independent of the limit read parameter.
  - `error` string: Curated failure message, present on failed runs.

## Other responses

- `400`: Invalid request. Criterion dialect violations carry a stable code and a field-addressable path; unknown execution fields (e.g. mode, max_moments) are rejected naming the field.
- `402`: Insufficient credit balance
- `403`: Usage limit reached (monthly find-moments runs, or the file limits when given a new URL) — `code: usage_limit_reached`
- `404`: File not found
- `500`: Internal server error

## Changes

- **2026-10-30** `23d3f240819f`: 6 info
  - added the non-success response with the status `403`
  - removed the non-success response with the status `429`
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `402` status
  - …2 more
- **2026-08-22** `d2a5205fc779`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/find-moments/post.md)

---

[API](https://skmtc.dev/cloudglue/apis/cloudglue-api.md) - [All operations](https://skmtc.dev/cloudglue/apis/cloudglue-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudglue/apis/cloudglue-api/revisions/23d3f240819f?raw)