---
title: "POST robots.v1.job.find_best_thumbnails.completed"
method: POST
path: "robots.v1.job.find_best_thumbnails.completed"
---

# POST robots.v1.job.find_best_thumbnails.completed

`POST robots.v1.job.find_best_thumbnails.completed` (webhook)

## Payload

- object
  - `type` 'robots.v1.job.find_best_thumbnails.completed', required: Type for the webhook event
  - `id` string, required: Unique identifier for the event
  - `created_at` string, date-time, required: Time the event was created
  - `object` object, required
    - `type` string, required
    - `id` string, required
  - `environment` object, required
    - `name` string, required: Name for the environment
    - `id` string, required: Unique identifier for the environment
  - `attempts` object[], required: Attempts for sending out the webhook event
    - `webhook_id` integer: Unique identifier for the webhook
    - `response_status_code` integer: HTTP response status code for the webhook attempt
    - `response_headers` object: HTTP response headers for the webhook attempt
    - `response_body` string, nullable: HTTP response body for the webhook attempt
    - `max_attempts` integer: Max attempts number for the webhook attempt
    - `id` string: Unique identifier for the webhook attempt
    - `created_at` string, date-time: Time the webhook request was attempted
    - `address` string: URL address for the webhook attempt
  - `data` object, required: Version 1 job delivered in the Mux webhook event data field. The event type identifies its workflow and transition.
    - `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` object: 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` object, 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` object: 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` string[]: 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` object[]: 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` object: Related Mux resources linked to this job.
      - `assets` object[], 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` object: Recorded asset thumbnail update outcome. Omitted when no outcome was recorded, including historical jobs.
        - `thumbnail` object
          - `status` 'updated' | 'failed', required: Outcome of the requested asset thumbnail update.
      - `best_thumbnails` object[], 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.

## Acknowledgement `200`

Return a 200 to indicate that the data was received successfully

---

[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)