*MCP › Reference › Platform › Workflows*

# Run a workflow

> Enqueues a run of the workflow, like the "Run" button in the interface, and returns its identifier and the status it is born with (`queued`).

> **Send your own idempotencyKey:** A retry without the same key duplicates the effect. Send your own `idempotencyKey` (a UUID) and resend the same one if you retry.

> **Requires human confirmation:** Put this tool on your client's “ask before running” list. The annotations are hints that the server declares, not guarantees: do not decide the approval from `destructiveHint` alone. The server flags this tool with `_meta["anthropic/requiresUserInteraction"]`, which clients that honor it use to ask a person before every call.

It does not wait for it to finish, and the API has no operation that reads a run yet: its progress is only visible in the Filmo application. If the workflow declares a run form, its fields are required and travel in `payload`; if any is missing it responds 400 without enqueueing anything. A workflow without any saved version responds 409. It accepts `Idempotency-Key`: two requests with the same key return the same run instead of enqueueing two.

TOOL `filmo_workflows_run` · `workflows:run` · 120/min · Server annotation: Destructive · Server annotation: Open world · Requires human confirmation · Send your own idempotencyKey

## Arguments

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workflowId` | string | Yes | Identifier of the workflow to run. |
| `payload` | object<string, any> | No | Values of the run form of the workflow, by field name. If the workflow declares fields they are REQUIRED and are validated against its published version: if any is missing the request responds 400 and nothing is queued. If it declares none, it is ignored. |
| `idempotencyKey` | string | No | Idempotency key chosen by the client (a UUID is recommended). Repeating the same key with the same arguments within 24 h returns the stored response without executing again; with different arguments it responds 422. It is the safe way to retry after a network failure. |

## Result

On success the result carries `structuredContent` with `data` and `meta`. These are the attributes of `data`.

| Name | Type | Description |
| --- | --- | --- |
| `runId` | string | Identifier of the queued run. |
| `state` | string | Initial state of the run. When just queued it is `queued`. `queued`, `running`, `waiting`, `paused`, `completed`, `failed`, `cancelled` |

*Call · filmo_workflows_run*

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "filmo_workflows_run",
    "arguments": {
      "workflowId": "work_8f2a1c",
      "idempotencyKey": "<a UUID you generate>"
    }
  }
}
```

*Result (generated from the schema)*

```json
{
  "structuredContent": {
    "data": {
      "runId": "run_8f2a1c",
      "state": "queued"
    },
    "meta": {
      "idempotencyKey": "<the key you sent, or the one the server generated>",
      "rateLimit": {
        "limit": 120,
        "remaining": 119,
        "reset": 42
      }
    }
  }
}
```

## The same operation by REST

This tool runs [`POST /api/v1/workflows/{workflowId}/runs`](https://docs.filmo.io/rest-api/endpoint-reference/workflows/run-a-workflow).

---

Canonical URL: https://docs.filmo.io/mcp/tools/workflows/filmo-workflows-run  
Last updated: 2026-10-25