---
title: "Trigger a directive run"
method: POST
path: "/robots/v1/directives/{DIRECTIVE_ID}/runs"
tags: ["Directives"]
---

# Trigger a directive run

`POST /robots/v1/directives/{DIRECTIVE_ID}/runs`

## Request

- Base URL: `https://api.mux.com`
- URL: `https://api.mux.com/robots/v1/directives/{DIRECTIVE_ID}/runs`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

Starts a v1 run for a v1 directive. A directive owned by v0 returns 404.

## Path parameters

- `DIRECTIVE_ID` string, required: Directive ID returned by directive creation or listing (drv_...).

## Request body

- RunDirectiveRequest
  - `asset_id` string, required: The bare Mux asset ID to run the directive against, as returned by the Mux Video API.

## Response `202`

V1 directive run started

- DirectiveRunResponse
  - `data` DirectiveRun, required
    - `id` string, required: Opaque run identifier (drvrun_...).
    - `directive_id` string, required: Opaque parent directive identifier (drv_...).
    - `subject_id` string, required: Bare Mux asset ID targeted by the run.
    - `status` 'pending' | 'dispatching' | 'running' | 'waiting' | 'completed' | 'partial' | 'errored', required
    - `node_states` DirectiveNodeState[], required: Per-binding state in configuration order. Failed nodes retain their reason diagnostic.
      - union
        - DirectiveNodeDispatched
          - `reference_id` string, required: Declared binding reference_id from directive.bindings[].
          - `status` 'dispatched', required
          - `job_id` string, required: Workflow job ID (rjob_...).
          - `workflow` 'analyze-structure' | 'summarize' | 'generate-contextual-text' | 'moderate' | 'generate-chapters' | 'edit-captions' | 'translate-captions' | 'translate-audio' | 'ask-questions' | 'find-key-moments' | 'generate-engagement-insights' | 'generate-premium-captions' | 'find-best-thumbnails', required: The Robots workflow for this binding.
        - DirectiveNodeFailed
          - `reference_id` string, required: Declared binding reference_id from directive.bindings[].
          - `status` 'failed', required
          - `reason` string, required: Human-readable diagnostic explaining why the binding didn't dispatch.
        - DirectiveNodeWaitingForResources
          - `reference_id` string, required: Declared binding reference_id from directive.bindings[].
          - `status` 'waiting_for_resources', required
          - `workflow` 'analyze-structure' | 'summarize' | 'generate-contextual-text' | 'moderate' | 'generate-chapters' | 'edit-captions' | 'translate-captions' | 'translate-audio' | 'ask-questions' | 'find-key-moments' | 'generate-engagement-insights' | 'generate-premium-captions' | 'find-best-thumbnails', required: The Robots workflow for this binding.
        - DirectiveNodeWaitingForSourceBindings
          - `reference_id` string, required: Declared binding reference_id from directive.bindings[].
          - `status` 'waiting_for_source_bindings', required
          - `workflow` 'analyze-structure' | 'summarize' | 'generate-contextual-text' | 'moderate' | 'generate-chapters' | 'edit-captions' | 'translate-captions' | 'translate-audio' | 'ask-questions' | 'find-key-moments' | 'generate-engagement-insights' | 'generate-premium-captions' | 'find-best-thumbnails', required: The Robots workflow for this binding.
          - `source_bindings` string[], required: reference_ids of producer bindings within this directive that must complete before this binding can dispatch.
    - `started_at` integer, required: Run start Unix timestamp in seconds.
    - `completed_at` integer, nullable, required: Terminal Unix timestamp in seconds, or null while in progress.

## Other responses

- `400`: Malformed or missing 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.
- `404`: Directive not found
- `409`: A run for this directive is already in progress
- `422`: Asset validation failed
- `500`: Server error

## Changes

- **2026-10-23** `ed6cb570d60c`: 1 info
  - endpoint added

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