---
title: "Create an 'ask-questions' job"
method: POST
path: "/robots/v0/jobs/ask-questions"
tags: ["Ask Questions"]
---

# Create an 'ask-questions' job

`POST /robots/v0/jobs/ask-questions`

Creates a new job that uses AI to answer questions about a Mux Video asset.

## Request body

- CreateAskQuestionsJobRequest
  - `passthrough` string — Arbitrary string stored with the job and returned in responses. Useful for correlating jobs with your own systems.
  - `parameters` AskQuestionsJobParameters, required
    - `asset_id` string, required — The Mux asset ID of the video to analyze.
    - `questions` object[], required — One or more questions to ask about the video. Each question can either select from answer_options (defaults to yes/no) or, by setting free_form_reply: true, receive a free-form prose answer.
      - `question` string, required — The question to ask about the video content.
      - `answer_options` string[] — Allowed answer values for this question. Defaults to ["yes", "no"] when omitted and free_form_reply is not true. Mutually exclusive with free_form_reply.
      - `free_form_reply` boolean — Experimental. When true, the model replies with free-form prose instead of selecting from answer_options. Mutually exclusive with answer_options. Treat the answer as untrusted model output.
    - `language_code` string — BCP 47 language code of the caption track to analyze (e.g. "en", "fr"). When omitted, the SDK uses the default track.
    - `max_free_form_answer_length` integer — Experimental. Max character length for free-form answers. Ignored unless at least one question sets free_form_reply: true.

## Response `202`

Ask questions job queued

- AskQuestionsJobResponse
  - `data` AskQuestionsJob, 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` 'ask-questions', required
    - `parameters` AskQuestionsJobParameters, required
      - `asset_id` string, required — The Mux asset ID of the video to analyze.
      - `questions` object[], required — One or more questions to ask about the video. Each question can either select from answer_options (defaults to yes/no) or, by setting free_form_reply: true, receive a free-form prose answer.
        - `question` string, required — The question to ask about the video content.
        - `answer_options` string[] — Allowed answer values for this question. Defaults to ["yes", "no"] when omitted and free_form_reply is not true. Mutually exclusive with free_form_reply.
        - `free_form_reply` boolean — Experimental. When true, the model replies with free-form prose instead of selecting from answer_options. Mutually exclusive with answer_options. Treat the answer as untrusted model output.
      - `language_code` string — BCP 47 language code of the caption track to analyze (e.g. "en", "fr"). When omitted, the SDK uses the default track.
      - `max_free_form_answer_length` integer — Experimental. Max character length for free-form answers. Ignored unless at least one question sets free_form_reply: true.
    - `status` 'pending' | 'processing' | 'completed' | 'errored' | 'cancelled', required — Current job status.
    - `outputs` AskQuestionsJobOutputs — Workflow results. Present when status is 'completed'.
      - `answers` object[], required — One answer per question, in the same order as the input questions.
        - `question` string, required — The original question that was asked.
        - `answer` string, nullable, required — For enum questions, constrained to one of the provided answer_options. For free-form questions, responds with prose up to max_free_form_answer_length characters - treat as untrusted model output. Null when the question was skipped.
        - `confidence` number, required — Confidence score from 0.0 to 1.0. Values above 0.9 indicate clear, unambiguous evidence; 0.7-0.9 strong evidence with minor ambiguity; 0.5-0.7 moderate evidence; below 0.5 weak or uncertain evidence. Always 0 when skipped.
        - `reasoning` string, required — Explanation citing specific visual or audio evidence from the video, or why the question was skipped.
        - `skipped` boolean, required — Whether the question was skipped due to irrelevance to the video content.
    - `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
- `403` — Robots is not enabled for this environment. Accept the Robots beta terms in the Mux Dashboard to enable access.
- `422` — Asset not found or missing playback ID
- `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)