--- title: "Get a 'find-best-thumbnails' job" method: GET path: "/robots/v1/jobs/find-best-thumbnails/{JOB_ID}" tags: ["Find Best Thumbnails"] --- # Get a 'find-best-thumbnails' job `GET /robots/v1/jobs/find-best-thumbnails/{JOB_ID}` ## Request - Base URL: `https://api.mux.com` - URL: `https://api.mux.com/robots/v1/jobs/find-best-thumbnails/{JOB_ID}` - Auth: one of: - HTTP basic - HTTP bearer Retrieves the current status and results of a 'find-best-thumbnails' job. Jobs are automatically deleted after 30 days. ## Path parameters - `JOB_ID` string, required: Robots job ID returned by job creation or listing (rjob_...). ## Response `200` Find best thumbnails job state - FindBestThumbnailsJobResponse - `data` FindBestThumbnailsJob, 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` JobDirectiveContext: 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-best-thumbnails', required - `parameters` FindBestThumbnailsJobParameters, required - `asset_id` string, required: The Mux asset ID of the video to find thumbnails for. - `max_thumbnails` integer: Maximum number of candidate thumbnails to return (1-5). Defaults to 5. - `output_steering` FindBestThumbnailsOutputSteering: Curated output_steering controls for execution scope, thumbnail scoring strategy, explicit user intent, audience, campaign style, and scoring priorities. Scope is enforced; other controls guide model behavior but do not guarantee exact output. - `scope` object: Optional sampling window in seconds on the original asset timeline, normalized inward to whole-millisecond half-open bounds. 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 thumbnail 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. - `selection_strategy` 'face_or_action' | 'clean_composition' | 'high_contrast' | 'brand_safe' | 'campaign_thumbnail': Best-effort guidance for what kind of thumbnail candidate should score highest. - `looking_for` string: Open-ended description of what the user is explicitly looking for in candidate thumbnails. Best-effort guidance only. - `audience` string: Intended audience used as best-effort scoring guidance. Does not change the output schema. - `campaign_style` string: Short description of the campaign/channel thumbnail style to prefer when supported by the frame. - `scoring_priorities` FindBestThumbnailsScoringPriority[]: Rubric criteria to emphasize in close calls. Best-effort guidance only. - `update_asset_thumbnail` boolean: When true, the highest-scoring thumbnail's timestamp is written to the Mux asset's thumbnail_time once the job completes, making that frame the asset's default poster image. The new thumbnail will appear for some clients sooner than others, depending on local cache settings. - `status` 'pending' | 'processing' | 'completed' | 'errored' | 'cancelled', required: Current job status. - `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. - `outputs` object: Workflow results. Present when status is 'completed'. - `asset_updates` FindBestThumbnailsAssetUpdateOutcomes: Recorded asset thumbnail update outcome. Omitted when no outcome was recorded, including historical jobs. - `thumbnail` FindBestThumbnailsThumbnailAssetUpdate - `status` 'updated' | 'failed', required: Outcome of the requested asset thumbnail update. - `best_thumbnails` FindBestThumbnailsCandidate[], required: Selected thumbnails, ordered best to worst by overall quality score. - `subscores` object, required: Per-category quality scores. - `focus` number, required: Sharpness and focus quality score (0-1). - `face_or_action` number, required: Presence of faces or dynamic action score (0-1). - `composition` number, required: Visual composition and framing quality score (0-1). - `contrast_color` number, required: Color contrast and vibrancy score (0-1). - `brand_fit` number, required: Alignment with brand guidelines score (0-1). - `overall` number, required: Overall quality score from 0 to 1. - `description` string, required: AI-generated description of the frame content. - `alt_text` string: Suggested alternative text for the candidate thumbnail image, suitable for use with the thumbnail URL in an accessible UI. - `time` number, required: Absolute frame timestamp in seconds on the original asset timeline. Fractional seconds are supported. ## Other responses - `401`: Missing or invalid Mux credentials - `403`: The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. For insufficient_scope, use credentials with the required permission. If using an API access token, create a replacement token with that permission. Enabling Robots for an organization does not grant token permissions. - `404`: No job exists for the supplied id - `422`: Invalid job ID - `500`: Server error ## Changes - **2026-10-23** `ed6cb570d60c`: 1 info - endpoint added [Operation history](https://skmtc.dev/muxinc/apis/mux-api/changes/robots/v1/jobs/find-best-thumbnails/:JOB_ID/get.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)