# Use the Mux Robots API
Learn how to use the Mux Robots API to run AI-powered workflows on your videos, including summarization, moderation, chapter generation, and more.
The Mux Robots API uses AI to extract structured data from your videos. Instead of integrating third-party AI services, managing async job queues, handling retries and failures, and writing custom glue code to tie it all together, you can send a single API request with an asset ID and get results back directly.

The Robots API is our recommended, batteries-included approach for adding AI to your video workflows — it handles model selection, prompting, retries, and webhook delivery so you can focus on using the results.

Robots is priced per Mux AI unit consumed by each job. See [Mux Robots pricing](/docs/pricing/overview#mux-robots-pricing) for rates and the current free-tier offer.

<Callout type="info" title="Need more control?">
  If you want to build your own AI workflows from lower-level primitives (transcripts, embeddings, custom prompts, your choice of LLM provider), check out [`@mux/ai`](https://github.com/muxinc/ai) — our open-source TypeScript SDK. It's a great fit when you need to customize the pipeline beyond what the Robots API exposes.
</Callout>

## What you can do

| Workflow | Description |
| :-- | :-- |
| [Summarize](/docs/guides/robots-summarize) | Generate a title, description, and tags for a video |
| [Moderate](/docs/guides/robots-moderate) | Analyze a video for inappropriate content |
| [Generate chapters](/docs/guides/robots-generate-chapters) | Create timestamped chapters from video content |
| [Ask questions](/docs/guides/robots-ask-questions) | Ask questions about a video and get structured answers |
| [Find key moments](/docs/guides/robots-find-key-moments) | Identify the most compelling moments in a video |
| [Translate captions](/docs/guides/robots-translate-captions) | Translate existing captions to another language |
| [Edit a video's captions](/docs/guides/robots-edit-captions) | Edit an existing caption track with static replacements and profanity censoring (experimental) |

## How it works

The Robots API is organized around **jobs**. A job represents a single unit of work — one row from the table above. Each type of work is called a **workflow**.

The general pattern is:

1. **Create a job** by sending a POST request to the workflow endpoint with your Mux asset ID and any configuration parameters.
2. **Wait for the job to complete.** Jobs move through statuses: `pending` → `processing` → `completed` (or `errored`). A job can also be `cancelled` via the cancel endpoint. We strongly encourage using [webhooks](/docs/core/listen-for-webhooks) for status changes, but jobs can also be retrieved through the `GET /robots/v0/jobs/{workflow}/{JOB_ID}` endpoint.
3. **Read the results** from the job's `outputs` field once the status is `completed`.

<Callout type="info">
  Jobs are automatically deleted after 30 days.
</Callout>

### Webhooks

Every status change fires a [webhook event](/docs/core/listen-for-webhooks). This lets you react to completed jobs without polling. The event type follows the pattern `robots.job.{workflow}.{status}`:

| Event type | Description |
| :-- | :-- |
| `robots.job.{workflow}.pending` | Job was created and is waiting to be picked up. |
| `robots.job.{workflow}.processing` | Job is actively running. |
| `robots.job.{workflow}.completed` | Job finished successfully. The full job object, including `outputs`, is in `event.data`. |
| `robots.job.{workflow}.errored` | Job failed. Check `event.data.errors` for details. |
| `robots.job.{workflow}.cancelled` | Job was cancelled before it completed. |

For example, a completed moderation job sends a `robots.job.moderate.completed` event. A completed summarization job sends `robots.job.summarize.completed`.

Note that multi-word workflow names use underscores in event types (e.g. `robots.job.ask_questions.completed`, `robots.job.find_key_moments.completed`), even though the API endpoints use hyphens.

The webhook payload's `data` field contains the full job object — the same shape you'd get from polling the job endpoint — so you can read `outputs` directly from the event without making an additional API call.

All Robots API endpoints live under `/robots/v0/`.

### Authentication

The Robots API uses the same Mux API token authentication as the rest of the Mux API. Include your token ID and secret using HTTP Basic Auth.

<Callout type="warning" title="Required scope">
  Your access token must have the `robots:*` scope in order to make requests to any Robots API endpoint. You can create or update access tokens in the [Mux Dashboard](https://dashboard.mux.com/settings/access-tokens).
</Callout>

```bash
curl https://api.mux.com/robots/v0/jobs/summarize \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{ "parameters": { "asset_id": "YOUR_ASSET_ID" } }' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
```

### Job lifecycle

Every job includes the following common fields:

| Field | Description |
| :-- | :-- |
| `id` | Unique job identifier |
| `status` | Current status: `pending`, `processing`, `completed`, `errored`, or `cancelled` |
| `workflow` | The workflow type (e.g. `summarize`, `moderate`) |
| `created_at` | Unix timestamp when the job was created |
| `updated_at` | Unix timestamp when the job was last updated |
| `passthrough` | An arbitrary string you can include when creating the job, returned as-is in responses |
| `parameters` | The input parameters for this job. Varies by workflow — see each workflow's guide for details. |
| `outputs` | Workflow results, present when status is `completed` |
| `units_consumed` | Number of Mux AI units consumed by this job |
| `errors` | Error details, present when status is `errored`. See the <ApiRefLink href="/docs/api-reference/robots/jobs">Robots API reference</ApiRefLink> for the full error structure. |
| `resources` | Related Mux resources linked to this job |

### Managing jobs

You can retrieve, list, cancel, and delete jobs across all workflows.

**Retrieve a job** by workflow and job ID:

```bash
curl https://api.mux.com/robots/v0/jobs/{workflow}/{JOB_ID} \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
```

Replace `{workflow}` with the workflow name used when the job was created (e.g. `summarize`, `moderate`, `generate-chapters`). The response includes the full job object with `outputs` when the job is `completed`.

**List jobs** with optional filters:

```bash
curl "https://api.mux.com/robots/v0/jobs?workflow=summarize&status=completed&limit=10" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
```

You can filter by `workflow`, `status`, `asset_id`, and paginate with `limit` (default 25, max 100) and `page` (default 1).

**Cancel a job** that is `pending` or `processing`. The job's status will transition to `cancelled`:

```bash
curl -X POST https://api.mux.com/robots/v0/jobs/{JOB_ID}/cancel \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
```