Introduction

A workflow is a graph of steps you build once in Studio and then run from outside the platform. Where running an agent is a single call to a single agent, a workflow chains several of them together with branching, loops, variables, and — where a decision needs a person — a human approval step.

You build the graph visually in Studio; everything in this section is about the half your integration touches: how a run is started, what it reads as input, when it becomes runnable at all, and what a run in flight looks like from the outside.

The shape of an integration

1. Build and save the graph in Studio (see Building a workflow).
2. Publish it. Until then, nothing outside Studio can run it — see Publishing.
3. Trigger it — from your own code with an API key, from another system with a signed webhook, from a person submitting a hosted form, or on a schedule. See Triggers.
4. Collect the result — synchronously for short runs, or by polling the run id for long ones. See the Workflows API reference.

Runs are durable

A workflow run is not an HTTP request that dies when your connection does. Starting a run creates a durable execution record, identified by an executionId, that keeps going in the background:

• The 30-second synchronous endpoint is a convenience, not a lifetime. If a run exceeds it you get a 504 — but the run keeps executing, and the executionId in that 504 body is how you collect it afterwards. This is deliberately unlike POST /agents/:agentId/run, which cancels its upstream run on timeout.
• Every run appears in Studio's Activity tab with its per-node status, whichever way it was triggered.
• A run that is still queued, running, paused, or awaiting_approval counts as in flight, and in-flight runs are what the concurrency ceiling below counts.
• A run parked on a Wait node shows as waiting. It is still open — you can cancel it, and it will resume on its own — but it is the one unfinished state that does not count against the ceiling, because nothing but the clock can release it.

Retrying a failed run

When a node fails, open it in the node editor. Its Output pane shows the error and a Retry from here button. Fix what failed (a node setting, an Agent's model settings, a secret), then press it.

A retry is a new run of the workflow's latest saved version, and the button saves your changes first. It runs the failed node and everything after it again. Every node that completed before that point is reused: its stored result is used as-is and it isn't called again, so no API calls or model calls are repeated. If/Else and Classify take the same branches as before, and variables keep their values. If the failed node is inside a Loop, the whole Loop runs again.

Sometimes the failed node isn't the one at fault. An earlier node completed, but its result was wrong, and the failure only showed up in a later node that used it. Retrying the failed node would reuse that wrong result and fail the same way. In that case, open the earlier node: every node that completed in a failed run has a Run again from here button. Fix that node, then press it. The node runs again, and so does everything after it, including the node that failed.

The retry shows in the Activity tab marked retry. The failed run stays as it was. A retry is refused if the node no longer exists in the latest version; run the workflow from the start in that case.

Concurrency ceiling

Each organization has a cap on how many workflow runs can be in flight at once. On the community plan that cap is 10; on the cloud and enterprise plans it is unlimited.

The ceiling is enforced identically on every external trigger — API, webhook, form, and schedule — so a burst on one path cannot starve another. A run rejected by it gets HTTP 429 and a durable record with status concurrency_limit_reached, so the Activity tab can explain what happened. Nothing is billed for it.

What this section does not cover

Authoring the graph itself — the node palette, wiring ports, configuring a node's prompt — is a Studio UI activity, not an API surface, and is not documented here. Building a workflow covers only the parts of that authoring which change what your integration sees.

Where to go next

• Building a workflow — the node types, and how input reaches them.
• Triggers — API, webhook, form, and recurrence.
• Publishing — why an unpublished workflow returns 409, and what a version pin is.
• Human review — what a run parked on an approval looks like.
• Workflows API reference — the endpoints themselves.