---
title: "List directive runs"
method: GET
path: "/robots/v1/directives/{DIRECTIVE_ID}/runs"
tags: ["Directives"]
---

# List directive runs

`GET /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

Returns a paginated list of runs for a directive, newest first. Runs are retained for 30 days.

## Path parameters

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

## Query parameters

- `limit` integer: Maximum number of results to return (default 25, max 100).
- `page` integer: Page number, 1-indexed (default 1).

## Response `200`

V1 directive runs

- DirectiveRunListResponse
  - `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.
  - `total_row_count` integer, required

## Other responses

- `401`: Missing or invalid Mux credentials
- `403`: The access token lacks robots:read (insufficient_scope), or Robots access is inactive or suspended. 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
- `422`: Invalid request parameters
- `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/get.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)