Running Workflows
This page has been cleared and is ready for updated Builder Studio documentation.
You run a workflow by triggering a node. Builder Studio plans the surrounding subgraph (see Workflows overview), admits the run, executes it on the server, and reports status back to the canvas. The same execution engine backs runs you start from the studio and runs started by agents, the API, or webhooks.
Ways to trigger a run
Every run is tagged with a trigger type. The supported ingress surfaces are manual, api, webhook, mcp, user-mcp, and replay.
| Trigger | How it starts | Where to learn more |
|---|---|---|
| Manual | You run a node from the studio. The browser admits the run through the manual start endpoint. | Canvas |
| API | A server-to-server call dispatches a canvas run with caller inputs. | API |
| Webhook | An inbound event hits a Webhook Trigger node and starts the downstream graph. | Webhook Trigger, Webhooks |
| MCP / user-MCP | An agent or external MCP client triggers a run through the MCP surface. | Builder MCP & CLI |
| Replay | An earlier execution is re-run — either in full or from a chosen step forward. | See “Replay” below. |
/api/execute/start, which accepts only the manual trigger type. Internal runtime dispatch (the work that actually executes steps) goes through /api/execute/worker. The older combined /api/execute endpoint is retired and returns 410. To trigger runs yourself, use the API or MCP / CLI surfaces rather than calling these internal routes directly.Running from the studio
Build and connect the graph
Place your nodes and wire their ports with edges so data flows from inputs to the node you want to produce. Only connected, executable nodes participate in the run.
Run the target node
Triggering a node admits a manual run for its subgraph. Builder Studio pre-checks that the workspace has enough credits for the billable steps before the run is accepted.
Watch status update live
Each node reflects its step status as the run progresses. Text Generation streams its output token by token; media nodes update when their generated result is written back.
Read the result
On success, generated media and text are applied to their nodes and stored with the canvas. On failure, the failed node shows its error and downstream nodes are skipped.
Triggering a run programmatically
External callers start runs by trigger type rather than by calling the internal worker directly. Manual browser admission accepts a stable Idempotency-Key: send the same key on a retry and the run replays instead of starting a duplicate execution. The body identifies the canvas to run.
POST /api/execute/startX-Trigger-Type: manual # only "manual" is accepted on /startIdempotency-Key: <stable-key> # optional; replays instead of re-runningContent-Type: application/json { "canvasId": "<canvasId>", "executionId": "<optional client-chosen id>"}Execution status
A run moves through a small set of statuses. The overall execution status is one of:
| Status | Meaning |
|---|---|
planning | The subgraph is being resolved and ordered into a plan. |
running | Steps are executing. |
waiting | The run is suspended at a waitpoint — for example, polling an async provider — and will resume when the result is ready. |
completed | Every step finished successfully. |
error | A step failed and the run could not complete. |
cancelled | The run was aborted before completing. |
Each step within a run carries its own status — pending, running, streaming, waiting, completed, error, or skipped. A step is skipped when an upstream dependency failed, or when a sibling in the same parallel group failed.
Suspension and resume
Some provider operations take long enough that the run should not hold a single request open. When a step hits a waitpoint, the run moves to waiting and records what it is waiting on. When the provider result arrives, the runtime resumes the run from that point and continues downstream. This is how async media generation completes without tying up the original trigger.
Cancellation, timeouts, and retries
- Cancellation aborts the run; remaining pending steps are marked skipped and the run settles as
cancelled. - Timeouts apply both at the whole-run level and per-step. Exceeding either aborts the affected work.
- Retriesare driven by each step's retry policy: on error a step retries with exponential backoff before it is treated as failed.
Replay
A previous execution can be replayed. A full replay re-runs the whole plan; a from-step replay re-runs from a chosen step forward, reusing the outputs of the steps before it. Replay is billed as a server-triggered run (see Credits & limits).
error or cancelled. The refund detail lives on the Credits & limits page.Was this page helpful?