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.

POST /find-moments

Find moments in a video

cURL

curl --request POST \
  --url https://api.cloudglue.dev/v1/find-moments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "criterion": {
    "name": "<string>",
    "instructions": "<string>",
    "moment_schema": {},
    "finding_schema": {},
    "anchors": {}
  },
  "describe_job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "signals_required": [
    "speech"
  ],
  "boundary_policy": "sentence",
  "speaker_filter": {
    "include": [
      "<string>"
    ],
    "exclude": [
      "<string>"
    ]
  },
  "min_duration_seconds": 5,
  "max_duration_seconds": 300,
  "cache_policy": "reuse"
}
'

200

{
  "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "created_at": 123,
  "url": "<string>",
  "find_moments_config": {
    "criterion": {
      "name": "<string>",
      "instructions": "<string>",
      "moment_schema": {},
      "finding_schema": {},
      "anchors": {},
      "scoring": {
        "key": "<string>",
        "min": 123,
        "max": 123,
        "higher_is_better": true,
        "description": "<string>"
      }
    },
    "criterion_hash": "<string>",
    "describe_job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "signals_required": [
      "<string>"
    ],
    "boundary_policy": "sentence",
    "speaker_filter": {},
    "min_duration_seconds": 123,
    "max_duration_seconds": 123,
    "cache_policy": "reuse",
    "engine_version": 123
  },
  "moments": [
    {
      "moment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "start_time": 123,
      "end_time": 123,
      "title": "<string>",
      "reason": "<string>",
      "rank_score": 0.5,
      "anchors": {},
      "speakers": [
        "<string>"
      ],
      "criterion_score": {
        "key": "<string>",
        "value": 123,
        "min": 123,
        "max": 123
      },
      "properties": {},
      "evidence": {
        "signals": [
          "<string>"
        ]
      }
    }
  ],
  "findings": [
    {
      "finding_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "kind": "absence",
      "properties": {}
    }
  ],
  "total_moments": 123,
  "error": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Find-moments run parameters

url · string · required

cloudglue://files/ or an ingestible URL (same resolution rules as describe/extract).

criterion · object · required

An inline criterion: rubric instructions plus typed output declarations. Snapshotted and hashed onto the run.

Show child attributes

describe_job_id · string<uuid>

Optional pin to a specific describe. It must exist for the file and its config must cover signals_required.

signals_required · enum<string>[]

Minimum array length: 1

Available options: speech, visual_scene_description, scene_text, audio_description

boundary_policy · enum<string> · default: sentence

Available options: sentence, tight, loose

speaker_filter · object

Show child attributes

min_duration_seconds · number · default: 5

Required range: x > 0

max_duration_seconds · number · default: 300

Required range: x > 0

cache_policy · enum<string> · default: reuse

Available options: reuse, refresh

Response

200

application/json

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

job_id · string<uuid> · required

status · enum<string> · required

Available options: pending, processing, completed, failed, cancelled

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.

Show child attributes

moments · object[]

Show child attributes

findings · object[]

Show child attributes

total_moments · integer

Full accepted count, independent of the limit read parameter.

error · string

Curated failure message, present on failed runs.