---
title: "Create a 'find-key-moments' job"
method: POST
path: "/robots/v0/jobs/find-key-moments"
tags: ["Find Key Moments"]
---

# Create a 'find-key-moments' job

`POST /robots/v0/jobs/find-key-moments`

Creates a new job that uses AI to identify key moments in a Mux Video asset.

## Request body

- CreateFindKeyMomentsJobRequest
  - `passthrough` string — Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.
  - `parameters` FindKeyMomentsJobParameters, required
    - `asset_id` string, required — The Mux asset ID of the video to analyze.
    - `max_moments` integer — Maximum number of key moments to extract. Defaults to 5.
    - `target_duration_ms` object — Preferred highlight duration range in milliseconds. When provided, the model will aim to select moments within this range.
      - `min` integer, required — Preferred minimum highlight duration in milliseconds.
      - `max` integer, required — Preferred maximum highlight duration in milliseconds.

## Response `202`

Key moments job queued

- FindKeyMomentsJobResponse
  - `data` FindKeyMomentsJob, required
    - `id` string, required — Unique job identifier.
    - `passthrough` string — Arbitrary string supplied at creation, returned as-is.
    - `units_consumed` integer, required — Number of Mux AI units consumed by this job.
    - `created_at` integer, required — Unix timestamp (seconds) when the job was created.
    - `updated_at` integer, required — Unix timestamp (seconds) when the job was last updated.
    - `workflow` 'find-key-moments', required
    - `parameters` FindKeyMomentsJobParameters, required
      - `asset_id` string, required — The Mux asset ID of the video to analyze.
      - `max_moments` integer — Maximum number of key moments to extract. Defaults to 5.
      - `target_duration_ms` object — Preferred highlight duration range in milliseconds. When provided, the model will aim to select moments within this range.
        - `min` integer, required — Preferred minimum highlight duration in milliseconds.
        - `max` integer, required — Preferred maximum highlight duration in milliseconds.
    - `status` 'pending' | 'processing' | 'completed' | 'errored' | 'cancelled', required — Current job status.
    - `outputs` FindKeyMomentsJobOutputs — Workflow results. Present when status is 'completed'.
      - `moments` object[], required — Extracted key moments, ordered by position in the video.
        - `start_ms` number, required — Moment start time in milliseconds.
        - `end_ms` number, required — Moment end time in milliseconds.
        - `cues` object[], required — Contiguous transcript segments that comprise this moment.
          - `start_ms` number, required — Cue start time in milliseconds.
          - `end_ms` number, required — Cue end time in milliseconds.
          - `text` string, required — Transcript text for this cue.
        - `overall_score` number, required — Weighted quality score from 0.0 to 1.0 based on hook strength, clarity, emotional intensity, novelty, and soundbite quality.
        - `title` string, required — Short catchy title for the moment (3-8 words).
        - `audible_narrative` string, required — One-sentence summary of what is being said during the moment.
        - `notable_audible_concepts` string[], required — Multi-word descriptive phrases (2-5 words each) capturing key audible concepts.
        - `visual_narrative` string — One-sentence summary of what is visually happening. Present for video assets only.
        - `notable_visual_concepts` object[] — Scored visual concepts extracted from sampled frames. Present for video assets only.
          - `concept` string, required — Multi-word visual concept (2-5 words).
          - `score` number, required — Relevance score from 0.0 to 1.0 measuring how closely the visual concept relates to the audible narrative.
          - `rationale` string, required — Brief explanation of the relevance score.
    - `errors` JobError[] — Error details. Present when status is 'errored'.
      - `type` string, required — Stable public error category identifier.
      - `message` string, required — Human-readable public error message.
      - `retryable` boolean — Whether retrying this job may resolve the error.
    - `resources` Resources — Related Mux resources linked to this job.
      - `assets` SlimlineAsset[], required — Mux assets associated with this job.
        - `id` string, required — Mux asset ID.
        - `meta` object — Mux asset metadata, if available.
          - `title` string — Asset title from Mux metadata.
          - `creator_id` string — Creator identifier from Mux metadata.
          - `external_id` string — External identifier from Mux metadata.
        - `passthrough` string — Passthrough string from the Mux asset.
        - `_links` object, required — Hypermedia links for the asset.
          - `self` object, required
            - `href` string, required — URL to the Mux asset resource.

## Other responses

- `401` — Missing Mux credentials for transcript access
- `403` — Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.
- `422` — Asset not found, missing playback ID, or no transcript
- `500` — Server error

---

[API](https://skmtc.net/muxinc/apis/mux-api.md) · [All operations](https://skmtc.net/muxinc/apis/mux-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/muxinc/mux-api/revisions/34a65dce0f31/schema)