---
title: "Create a 'find-scenes' job"
method: POST
path: "/robots/v0/jobs/find-scenes"
tags: ["Find Scenes (v0)"]
deprecated: true
---

# Create a 'find-scenes' job

`POST /robots/v0/jobs/find-scenes`

## Request

- Base URL: `https://api.mux.com`
- URL: `https://api.mux.com/robots/v0/jobs/find-scenes`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

> **Deprecated.**

Deprecated: use `POST /robots/v1/jobs/analyze-structure` instead. Creates a new job that segments a Mux video asset into ordered scenes using storyboard-backed generated shots for shot-level visual evidence, combined with transcript cues when available. If the asset has no generated shots, the job generates them on demand and waits for completion — they do not need to exist beforehand. Optional output steering can restrict execution to a time scope in seconds and guide segmentation strategy, title style, narration detail, audience, brand terms, and topic taxonomy without changing the response schema. Scoped results retain absolute timestamps on the original asset timeline.

## Request body

- CreateFindScenesJobRequestV0
  - `passthrough` string: Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.
  - `parameters` FindScenesJobParametersV0, required
    - `asset_id` string, required: The Mux asset ID of the video asset to segment into scenes. Audio-only assets are not supported.
    - `language_code` string: Preferred transcript language code to analyze when a matching transcript track is available. Defaults to the first ready transcript track on the asset.
    - `min_scenes` integer: Optional lower-bound hint for scene segmentation. When provided, the model should avoid collapsing clearly distinct beats below this count when the content supports more granular scene boundaries.
    - `min_scene_duration_ms` integer: Preferred minimum scene duration in milliseconds for scaffolded transcript chunking. Defaults to 15000.
    - `output_steering` FindScenesOutputSteeringV0: Curated output_steering controls for execution scope, segmentation strategy, title style, narration detail, audience, brand terms, and topic taxonomy. Scope is enforced; other controls guide model behavior but do not guarantee exact output.
      - `scope` object: Optional execution window in seconds on the original asset timeline. The range must contain a video frame at the asset frame rate. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Returned scene timestamps remain absolute asset timestamps.
        - `start_time` number: Start of the execution window in seconds from the beginning of the media. When omitted, the window starts at the beginning.
        - `end_time` number: End of the execution window in seconds from the beginning of the media. When omitted, the window extends to the end.
      - `segmentation_strategy` 'editorial_beats' | 'topic_changes' | 'visual_transitions' | 'action_progression' | 'instructional_steps': Best-effort guidance for the kinds of boundaries the scene finder should prefer.
      - `title_style` 'descriptive' | 'editorial' | 'search_optimized' | 'accessibility': Best-effort title style guidance for generated scene titles.
      - `narration_detail` 'concise' | 'balanced' | 'detailed': Best-effort guidance for how much detail scene narratives should include.
      - `audience` string: Intended audience used as best-effort model guidance. Does not change the output schema.
      - `brand_terms` string[]: Preferred brand or domain terms to use when supported by source evidence.
      - `topic_taxonomy` object: Controlled vocabulary used to steer scene concepts without changing the response schema.
        - `name` string: Optional customer-facing name for the taxonomy.
        - `values` OutputSteeringTaxonomyValueV0[], required: Controlled vocabulary values used as best-effort model guidance.
          - `label` string, required: Canonical taxonomy value to prefer when supported by the source content.
          - `description` string: Short explanation of when this value applies.
          - `aliases` string[]: Accepted alternate names that should normalize to the canonical label.
        - `allow_other` boolean, required: When false, the model should prefer values from the taxonomy. When true, non-taxonomy values may be used when no taxonomy value applies.

## Response `202`

Find scenes job queued

- FindScenesJobResponseV0
  - `data` FindScenesJobV0, 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.
    - `directive` JobDirectiveContextV0: The directive run that dispatched this job. Absent for jobs created via direct API POST.
      - `id` string, required: ID of the directive that dispatched this job.
      - `run_id` string, required: ID of the specific directive run that dispatched this job.
    - `created_at` integer, required: Unix timestamp (seconds) when the job was created.
    - `updated_at` integer, required: Unix timestamp (seconds) of the job's last state transition (e.g. when it started processing or reached a terminal state).
    - `workflow` 'find-scenes', required
    - `parameters` FindScenesJobParametersV0, required
      - `asset_id` string, required: The Mux asset ID of the video asset to segment into scenes. Audio-only assets are not supported.
      - `language_code` string: Preferred transcript language code to analyze when a matching transcript track is available. Defaults to the first ready transcript track on the asset.
      - `min_scenes` integer: Optional lower-bound hint for scene segmentation. When provided, the model should avoid collapsing clearly distinct beats below this count when the content supports more granular scene boundaries.
      - `min_scene_duration_ms` integer: Preferred minimum scene duration in milliseconds for scaffolded transcript chunking. Defaults to 15000.
      - `output_steering` FindScenesOutputSteeringV0: Curated output_steering controls for execution scope, segmentation strategy, title style, narration detail, audience, brand terms, and topic taxonomy. Scope is enforced; other controls guide model behavior but do not guarantee exact output.
        - `scope` object: Optional execution window in seconds on the original asset timeline. The range must contain a video frame at the asset frame rate. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Returned scene timestamps remain absolute asset timestamps.
          - `start_time` number: Start of the execution window in seconds from the beginning of the media. When omitted, the window starts at the beginning.
          - `end_time` number: End of the execution window in seconds from the beginning of the media. When omitted, the window extends to the end.
        - `segmentation_strategy` 'editorial_beats' | 'topic_changes' | 'visual_transitions' | 'action_progression' | 'instructional_steps': Best-effort guidance for the kinds of boundaries the scene finder should prefer.
        - `title_style` 'descriptive' | 'editorial' | 'search_optimized' | 'accessibility': Best-effort title style guidance for generated scene titles.
        - `narration_detail` 'concise' | 'balanced' | 'detailed': Best-effort guidance for how much detail scene narratives should include.
        - `audience` string: Intended audience used as best-effort model guidance. Does not change the output schema.
        - `brand_terms` string[]: Preferred brand or domain terms to use when supported by source evidence.
        - `topic_taxonomy` object: Controlled vocabulary used to steer scene concepts without changing the response schema.
          - `name` string: Optional customer-facing name for the taxonomy.
          - `values` OutputSteeringTaxonomyValueV0[], required: Controlled vocabulary values used as best-effort model guidance.
            - `label` string, required: Canonical taxonomy value to prefer when supported by the source content.
            - `description` string: Short explanation of when this value applies.
            - `aliases` string[]: Accepted alternate names that should normalize to the canonical label.
          - `allow_other` boolean, required: When false, the model should prefer values from the taxonomy. When true, non-taxonomy values may be used when no taxonomy value applies.
    - `status` 'pending' | 'processing' | 'completed' | 'errored' | 'cancelled', required: Current job status.
    - `errors` JobErrorV0[]: 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` ResourcesV0: Related Mux resources linked to this job.
      - `assets` SlimlineAssetV0[], 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.
    - `outputs` FindScenesJobOutputsV0: Workflow results. Present when status is 'completed'.
      - `scenes` object[], required: Ordered scene segments extracted from the original asset timeline using shot boundaries plus any available transcript context.
        - `start_ms` number, required: Scene start time in milliseconds.
        - `end_ms` number, required: Scene end time in milliseconds.
        - `title` string, required: Short human-readable title for the scene.
        - `cues` object[], required: Transcript cues that overlap the scene. Can be empty when no usable transcript is available.
          - `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.
        - `audible_narrative` string: One-sentence summary of what is being said during the scene. Present only when transcript cues are available.
        - `blended_narrative` string: Combined audible and visual narrative for the scene when both signals are meaningfully available. Omit when no transcript-backed audible signal exists.
        - `notable_audible_concepts` string[]: Multi-word descriptive phrases capturing key audible concepts in the scene. Present only when transcript cues are available.
        - `visual_narrative` string: One-sentence summary of what is visually happening during the scene. Present for video assets when visual enrichment succeeds.
        - `notable_visual_concepts` object[]: Scored visual concepts extracted from sampled scene frames. Present for video assets when visual enrichment succeeds.
          - `concept` string, required: Multi-word visual concept (2-5 words).
          - `score` number, required: Salience score from 0.0 to 1.0 measuring how visually important the concept is within the scene.
          - `rationale` string, required: Brief explanation of why the concept is visually important for the scene.
        - `shots` object[]: Optional ordered shot or beat breakdown within the scene, including timings and short visual descriptions.
          - `start_ms` number, required: Shot or beat start time in milliseconds within the scene.
          - `end_ms` number, required: Shot or beat end time in milliseconds within the scene.
          - `visual_description` string, required: Short visual description of what happens during this shot or beat.
        - `shot_count` integer, required: How many timed shot or beat entries make up the scene. When shots is present, this equals shots.length.

## Other responses

- `400`: Malformed or missing JSON request body, or invalid request parameters
- `401`: Missing or invalid Mux credentials
- `403`: Robots is not enabled for this environment (accept the Robots beta terms in the Mux Dashboard to enable access), or a free-plan limit has prevented job creation.
- `409`: A job with the same workflow and parameters is already pending or processing for this environment.
- `422`: Asset not found, not a video asset, or missing public or signed playback ID
- `500`: Server error

## Changes

- **2026-10-26** `151835caff06`: 1 info
  - endpoint deprecated
- **2026-10-19** `7e2e5079412d`: 3 breaking, 3 warning, 9 info
  - added `#/components/schemas/OutputSteeringBrandTermsV0` to the `parameters/output_steering/brand_terms` request property `allOf` list
  - added `#/components/schemas/OutputSteeringScopeV0` to the `parameters/output_steering/scope` request property `allOf` list
  - added `#/components/schemas/OutputSteeringTaxonomyV0` to the `parameters/output_steering/topic_taxonomy` request property `allOf` list
  - removed `#/components/schemas/OutputSteeringBrandTerms` from the `parameters/output_steering/brand_terms` request property `allOf` list
  - …11 more
- **2026-10-08** `296f0b01bb84`: 11 info
  - added the non-success response with the status `400`
  - added the optional property `error/messages` to the response with the `401` status
  - added the optional property `error/messages` to the response with the `403` status
  - added the optional property `error/messages` to the response with the `409` status
  - …7 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/muxinc/apis/mux-api/changes/robots/v0/jobs/find-scenes/post.md)

---

[API](https://skmtc.dev/muxinc/apis/mux-api.md) - [All operations](https://skmtc.dev/muxinc/apis/mux-api/llms.txt) - [OpenAPI document](https://skmtc.dev/muxinc/apis/mux-api/revisions/75b4251a1d96?raw)