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).

Tool

filmo_workflows_run

Destructiveworkflows:run

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

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

{
  "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
      }
    }
  }
}

generated from the schema

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.

Arguments

workflowIdstringRequired

Identifier of the workflow to run.

Limits: min length 1

payloadobject<string, any>

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.

idempotencyKeystring

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.

Limits: min length 1, max length 255

Result

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

Show the attributes of data

runIdstring

Identifier of the queued run.

statestring

Initial state of the run. When just queued it is queued.

Available options: queued, running, waiting, paused, completed, failed, cancelled

An error is a result with isError: true and the problem in content[0].text; there is no structuredContent. See Errors.

The same operation by REST

This tool runs POST /api/v1/workflows/{workflowId}/runs.

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).
Guides
Safe writes
An assistant that can write can also write the wrong thing. Decide which tools need a person, retry without duplicating, and know what a write sets in motion.
Guides
Errors
A tool error is a result with isError: true and the problem in the first text block. Branch on its code.

Was this page helpful?

Result

Arguments

Result

The same operation by REST

Related pages

Run a workflow

Safe writes

Errors