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

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


## OpenAPI

````yaml POST /find-moments
openapi: 3.0.0
info:
  title: Cloudglue API
  description: API for Cloudglue
  license:
    name: Apache License 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 0.7.23
servers:
  - url: https://api.cloudglue.dev/v1
security:
  - bearerAuth: []
paths:
  /find-moments:
    post:
      tags:
        - Find Moments
      summary: Find moments in a video
      description: >-
        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.
      operationId: createFindMoments
      requestBody:
        description: Find-moments run parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewFindMoments'
        required: true
      responses:
        '200':
          description: The created run, or an existing matching run at cost 0 (cache hit).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindMoments'
        '400':
          description: >-
            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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: Insufficient credit balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: File not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Monthly find-moments runs limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    NewFindMoments:
      type: object
      properties:
        url:
          type: string
          description: >-
            cloudglue://files/<id> or an ingestible URL (same resolution rules
            as describe/extract).
        describe_job_id:
          type: string
          format: uuid
          description: >-
            Optional pin to a specific describe. It must exist for the file and
            its config must cover signals_required.
        criterion:
          $ref: '#/components/schemas/MomentCriterion'
        signals_required:
          type: array
          minItems: 1
          default:
            - speech
          items:
            type: string
            enum:
              - speech
              - visual_scene_description
              - scene_text
              - audio_description
        boundary_policy:
          type: string
          enum:
            - sentence
            - tight
            - loose
          default: sentence
        speaker_filter:
          type: object
          properties:
            include:
              type: array
              items:
                type: string
            exclude:
              type: array
              items:
                type: string
            match:
              type: string
              enum:
                - any
                - all
        min_duration_seconds:
          type: number
          minimum: 0
          exclusiveMinimum: true
          default: 5
        max_duration_seconds:
          type: number
          minimum: 0
          exclusiveMinimum: true
          default: 300
        cache_policy:
          type: string
          enum:
            - reuse
            - refresh
          default: reuse
      required:
        - url
        - criterion
      additionalProperties: false
    FindMoments:
      type: object
      properties:
        job_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
        created_at:
          type: integer
          description: Unix timestamp in milliseconds when the run was created
        url:
          type: string
        find_moments_config:
          type: object
          description: >-
            Echo of the request plus criterion_hash and the resolved
            describe_job_id.
        moments:
          type: array
          items:
            $ref: '#/components/schemas/Moment'
        findings:
          type: array
          items:
            $ref: '#/components/schemas/MomentFinding'
        total_moments:
          type: integer
          description: Full accepted count, independent of the limit read parameter.
        error:
          type: string
          description: Curated failure message, present on failed runs.
      required:
        - job_id
        - status
        - created_at
        - url
    Error:
      required:
        - error
      type: object
      properties:
        error:
          type: string
    MomentCriterion:
      type: object
      description: >-
        An inline criterion: rubric instructions plus typed output declarations.
        Snapshotted and hashed onto the run.
      properties:
        name:
          type: string
          pattern: ^[a-z][a-z0-9_]*$
          maxLength: 64
        instructions:
          type: string
          minLength: 1
          description: The complete rubric, including any seed lists and worked examples.
        moment_schema:
          $ref: '#/components/schemas/MomentSchemaDefinition'
        finding_schema:
          $ref: '#/components/schemas/MomentSchemaDefinition'
        anchors:
          type: object
          description: >-
            Named intra-moment timestamps. A non-required anchor that does not
            exist is omitted from the moment - never null.
          additionalProperties:
            type: object
            properties:
              required:
                type: boolean
              description:
                type: string
        scoring:
          type: object
          description: >-
            The rubric's single canonical score: what rank-ordered reads sort by
            and what min_score filters on. Exactly one scoring key per
            criterion.
          properties:
            key:
              type: string
            min:
              type: number
            max:
              type: number
            higher_is_better:
              type: boolean
            description:
              type: string
          required:
            - key
            - min
            - max
      required:
        - name
        - instructions
    Moment:
      type: object
      properties:
        moment_id:
          type: string
          format: uuid
        start_time:
          type: number
          description: Seconds from source start.
        end_time:
          type: number
        anchors:
          type: object
          additionalProperties:
            type: number
          description: >-
            Declared anchors only; an anchor that was not found is absent, never
            null.
        title:
          type: string
        reason:
          type: string
        speakers:
          type: array
          items:
            type: string
        criterion_score:
          $ref: '#/components/schemas/CriterionScore'
        rank_score:
          type: number
          minimum: 0
          maximum: 1
          description: Normalized ordering within the run; what the default sort uses.
        properties:
          type: object
          description: Validates against the criterion's moment_schema.
        evidence:
          type: object
          properties:
            signals:
              type: array
              items:
                type: string
      required:
        - moment_id
        - start_time
        - end_time
        - title
        - reason
        - rank_score
    MomentFinding:
      type: object
      description: >-
        A non-temporal finding, produced whenever the criterion declares a
        finding_schema.
      properties:
        finding_id:
          type: string
          format: uuid
        kind:
          type: string
          enum:
            - absence
            - observation
        properties:
          type: object
          description: Validates against the criterion's finding_schema.
      required:
        - finding_id
        - kind
        - properties
    MomentSchemaDefinition:
      type: object
      description: >-
        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.
    CriterionScore:
      type: object
      description: The rubric's judgment on its own declared scale.
      properties:
        key:
          type: string
        value:
          type: number
        min:
          type: number
        max:
          type: number
      required:
        - key
        - value
        - min
        - max
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````