---
title: "Create a 'moderate' job"
method: POST
path: "/robots/v1/jobs/moderate"
tags: ["Moderate"]
---

# Create a 'moderate' job

`POST /robots/v1/jobs/moderate`

## Request

- Base URL: `https://api.mux.com`
- URL: `https://api.mux.com/robots/v1/jobs/moderate`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

Creates a new job that uses AI to analyze a Mux Video asset for inappropriate content. Optional output steering can restrict execution to a time scope in seconds.

## Request body

- CreateModerateJobRequest
  - `passthrough` string: Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.
  - `parameters` ModerateJobParameters, required
    - `asset_id` string, required: The Mux asset ID of the video to moderate.
    - `language_code` string: BCP 47 language code of the caption source. An explicit language must match a ready source exactly, including case; for example, en does not match en-US. Translation target exclusion and track replacement instead compare base languages case-insensitively. When omitted, automatic selection applies. Uses the first ready subtitle in asset track order without English preference. Audio-only assets with one ready text track lacking subtitle metadata can use that legacy transcript.
    - `thresholds` object: Score thresholds that determine whether content is flagged. When combined with sampling_interval or max_samples, the exceeds_threshold flag reflects whether any category's highest observed score exceeds its configured threshold. Defaults to {sexual: 0.7, violence: 0.8}.
      - `sexual` number: Score threshold for sexual content. Content scoring above this value triggers exceeds_threshold.
      - `violence` number: Score threshold for violent content. Content scoring above this value triggers exceeds_threshold.
    - `sampling_interval` integer: Interval, in seconds, between sampled thumbnails. Minimum 5 seconds. When max_samples is also set, the actual sampling density is the more restrictive of the two constraints.
    - `max_samples` integer: Maximum number of thumbnails to sample. Acts as a cap — if sampling_interval produces fewer samples than this limit, the interval is respected; otherwise samples are evenly distributed with first and last frames pinned.
    - `output_steering` ModerateOutputSteering: Curated controls that optionally restrict moderation to an asset time range.
      - `scope` object: Optional execution window in seconds on the original asset timeline. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Moderation is restricted to media within this window, while returned 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.
    - `on_flagged` ActionOnFlagged: Optional action taken automatically when exceeds_threshold is true. When omitted, the job only reports scores and takes no action. Note: in a directive run that targets the same asset with other workflows, deleting playback IDs can break sibling workflows that need a playback ID.
      - `action` 'delete_playback_ids', required: Action to take when exceeds_threshold is true. "delete_playback_ids" deletes every playback ID on the asset, making it unplayable while preserving the underlying asset so it can be re-published or reviewed.
    - `include_transcript` boolean: Whether to moderate the asset's caption transcript in addition to sampled thumbnails. Applies to video assets with a ready caption track; audio-only assets are always moderated on their transcript. Set to false to moderate thumbnails only.

## Response `202`

Job queued

- ModerateJobResponse
  - `data` ModerateJob, 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` 'moderate', required
    - `parameters` ModerateJobParameters, required
      - `asset_id` string, required: The Mux asset ID of the video to moderate.
      - `language_code` string: BCP 47 language code of the caption source. An explicit language must match a ready source exactly, including case; for example, en does not match en-US. Translation target exclusion and track replacement instead compare base languages case-insensitively. When omitted, automatic selection applies. Uses the first ready subtitle in asset track order without English preference. Audio-only assets with one ready text track lacking subtitle metadata can use that legacy transcript.
      - `thresholds` object: Score thresholds that determine whether content is flagged. When combined with sampling_interval or max_samples, the exceeds_threshold flag reflects whether any category's highest observed score exceeds its configured threshold. Defaults to {sexual: 0.7, violence: 0.8}.
        - `sexual` number: Score threshold for sexual content. Content scoring above this value triggers exceeds_threshold.
        - `violence` number: Score threshold for violent content. Content scoring above this value triggers exceeds_threshold.
      - `sampling_interval` integer: Interval, in seconds, between sampled thumbnails. Minimum 5 seconds. When max_samples is also set, the actual sampling density is the more restrictive of the two constraints.
      - `max_samples` integer: Maximum number of thumbnails to sample. Acts as a cap — if sampling_interval produces fewer samples than this limit, the interval is respected; otherwise samples are evenly distributed with first and last frames pinned.
      - `output_steering` ModerateOutputSteering: Curated controls that optionally restrict moderation to an asset time range.
        - `scope` object: Optional execution window in seconds on the original asset timeline. Omit start_time to begin at the asset start and omit end_time to continue through the asset end. Moderation is restricted to media within this window, while returned 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.
      - `on_flagged` ActionOnFlagged: Optional action taken automatically when exceeds_threshold is true. When omitted, the job only reports scores and takes no action. Note: in a directive run that targets the same asset with other workflows, deleting playback IDs can break sibling workflows that need a playback ID.
        - `action` 'delete_playback_ids', required: Action to take when exceeds_threshold is true. "delete_playback_ids" deletes every playback ID on the asset, making it unplayable while preserving the underlying asset so it can be re-published or reviewed.
      - `include_transcript` boolean: Whether to moderate the asset's caption transcript in addition to sampled thumbnails. Applies to video assets with a ready caption track; audio-only assets are always moderated on their transcript. Set to false to moderate thumbnails only.
    - `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'.
      - `thumbnail_scores` object[], required: Per-thumbnail moderation scores. Empty for audio-only assets.
        - `time` number, required: Time in seconds of the thumbnail within the video.
        - `sexual` number, required: Sexual content score from 0.0 to 1.0.
        - `violence` number, required: Violence content score from 0.0 to 1.0.
      - `max_scores` object, required: Highest scores across every moderated thumbnail and transcript window for each category.
        - `sexual` number, required
        - `violence` number, required
      - `exceeds_threshold` boolean, required: True if any category's max score exceeds its configured threshold.
      - `flagged_action` object: Present only when on_flagged was set and exceeds_threshold was true. Records the action taken and which playback IDs were deleted.
        - `action` 'delete_playback_ids', required
        - `deleted_playback_ids` string[], required: Playback IDs that were deleted from the asset because it exceeded the threshold.
      - `transcript_scores` object[], required: Per-window transcript moderation scores. Empty when transcript moderation was skipped.
        - `start_time` number, required: Time in seconds where the moderated transcript window starts.
        - `end_time` number, required: Time in seconds where the moderated transcript window ends.
        - `sexual` number, required: Sexual content score from 0.0 to 1.0.
        - `violence` number, required: Violence content score from 0.0 to 1.0.
      - `thumbnail_moderation` object, required: Outcome of thumbnail moderation.
        - `status` 'completed' | 'skipped' | 'failed', required: "completed" if at least one thumbnail was moderated, "skipped" if nothing could be moderated on this surface (see skip_reason), "failed" if every thumbnail errored so this surface contributed no scores.
        - `skip_reason` 'no_video_track' | 'no_video_in_scope': Present only when status is "skipped". Machine-readable reason nothing was moderated.
        - `skip_message` string: Present only when status is "skipped". Human-readable explanation of skip_reason.
      - `transcript_moderation` object, required: Outcome of transcript moderation.
        - `status` 'completed' | 'skipped' | 'failed', required: "completed" if at least one transcript window was moderated, "skipped" if nothing could be moderated on this surface (see skip_reason), "failed" if every transcript window errored so this surface contributed no scores.
        - `skip_reason` 'no_ready_text_track' | 'no_cues' | 'disabled': Present only when status is "skipped". Machine-readable reason nothing was moderated.
        - `skip_message` string: Present only when status is "skipped". Human-readable explanation of skip_reason.

## Other responses

- `400`: Malformed JSON request body.
- `401`: Missing or invalid Mux credentials
- `403`: The access token lacks robots:write (insufficient_scope), or Robots access is inactive or suspended. A free-plan workflow or unit limit can also prevent creation. 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.
- `409`: Resource conflict. See the error type and messages for details.
- `422`: Asset not found or errored, missing public or signed playback access, missing or ineligible required audio captions, or no eligible source matching the explicit audio caption language.
- `500`: Server error

## Changes

- **2026-11-03** `c0880e92f3ea`: 6 info
  - added the new optional request property `parameters/include_transcript`
  - added the optional property `data/parameters/include_transcript` to the response with the `202` status
  - the response property `data/outputs/allOf[#/components/schemas/ModerateJobOutputs]/thumbnail_scores/items/time` became required for the status `202`
  - added the required property `data/outputs/allOf[#/components/schemas/ModerateJobOutputs]/thumbnail_moderation` to the response with the `202` status
  - …2 more
- **2026-10-26** `151835caff06`: 3 breaking
  - removed the required property `data/outputs/allOf[#/components/schemas/ModerateJobOutputs]/thumbnail_moderation` from the response with the `202` status
  - removed the required property `data/outputs/allOf[#/components/schemas/ModerateJobOutputs]/transcript_moderation` from the response with the `202` status
  - removed the required property `data/outputs/allOf[#/components/schemas/ModerateJobOutputs]/transcript_scores` from the response with the `202` status
- **2026-10-23** `ed6cb570d60c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/muxinc/apis/mux-api/changes/robots/v1/jobs/moderate/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)