run_workflow
Queue a ComfyUI workflow for execution, optionally wait for completion, and return status, node errors, output file references, data values, and a preview thumbnail.
Instructions
Queue the workflow and (by default) wait for completion. Returns status, node errors on failure, output file refs, any non-file return values (data_outputs: generated text, paths a save node wrote), and an inline preview thumbnail so you can SEE the result (view_output fetches full size). wait=False returns {status: queued, prompt_id} - poll get_run_status. Prove a workflow works before saving.
return_preview=False (text-only caller): no inline images, sweeps included; a file path comes back if save_dir/COMFYUI_MOUNT_DIR is set.
roll_seeds=True (default) mirrors the browser: randomize/increment/decrement seeds and PrimitiveNodes re-roll and persist before submit. False re-runs the stored values.
allow_invalid=True submits despite local validation errors (ComfyUI is the final judge). save_dir (or COMFYUI_MOUNT_DIR) relocates finished outputs into a folder the caller can reach (saved_paths); needs wait=True - a background run relocates later via save_output(prompt_id=...).
front: None (default) refuses to queue when >=2 prompts are pending and returns {status: queue_busy} so the USER can choose; True runs next; False waits at the back of the line.
confirm_spend: partner/API nodes charge per submit, so a graph containing one is gated - pass True only after they agree.
sweep={variants:[{label,ops}],seeds:[int],crops:[[x0,y0,x1,y1]],reference?: "file [input]",freeze?:node_id}: each variant (ops on a copy) x seed; returns a contact sheet (reference = first cell), 1:1 crop sheets, per-run elapsed_s/files. <=24 runs, wait=True; crops <=512px or 0-1 floats.
LONG RENDERS: a timeout cancels your wait, not the job. wait=False, front=False, poll get_run_status(prompt_id) to success/error/partial, then save_output; manage_queue(status).draftsman_submitted keeps prompt_ids.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"workflow_id": "<workflow_id>"
},
"name": "run_workflow"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| wait | No | ||
| front | No | ||
| sweep | No | ||
| save_dir | No | ||
| roll_seeds | No | ||
| workflow_id | Yes | ||
| allow_invalid | No | ||
| confirm_spend | No | ||
| return_preview | No | ||
| timeout_seconds | No |