Running workflows

Start a run with one request, then follow it until it finishes. Runs are queued, so the start request returns at once with an execution ID.

All examples send the key in x-api-key. See Authentication and API keys.

Start a run

POST /api/workflows/{workflowId}/execute. Needs workflows:write.

The body is optional:

Field	Type	Meaning
`input`	object	Data for the run. Nodes read it as the trigger data.
`triggerNodeId`	string	The trigger node to start from, when the workflow has more than one
`executionMode`	string	`normal` (default), `test`, `debug` or `sandbox`. `sandbox` runs against mock data. See Sandbox mode.

curl -X POST "https://<your-flero-address>/api/workflows/<workflowId>/execute" \
  -H "x-api-key: dk_..." \
  -H "Content-Type: application/json" \
  -d '{"input": {"customerEmail": "[email protected]"}, "executionMode": "sandbox"}'

Response, 202 Accepted:

{
  "message": "Workflow execution has been queued.",
  "executionId": "…",
  "workers": {"live": 1, "consuming": 1}
}

If no worker is available to pick up the run, the response also carries a warning. The run waits in pending until a worker is free.

Which version runs

The execute endpoint runs the latest saved version of the workflow, even if a different version is active. A workflow with no saved version answers 409 with code NO_ACTIVE_VERSION. Save it in the editor first. See Versions and activation.

Follow a run

GET /api/executions/{executionId}. Needs executions:read.

curl "https://<your-flero-address>/api/executions/<executionId>" \
  -H "x-api-key: dk_..."

The response includes:

Field	Meaning
`status`	Where the run is. See the table below.
`startedAt`, `finishedAt`	Timestamps
`currentNodeId`	The node running now, while the run is in progress
`progress`	Per-node status and output
`data`	The trigger data and run metadata
`workflowVersionId`	The version that ran

Add ?slim=true to skip node outputs when you only need the status.

Status values

Status	Meaning	Finished?
`pending`	Queued, waiting for a worker	No
`running`	In progress	No
`paused`	Paused by a person	No
`waiting_for_input`	Waiting for an approval	No
`waiting_for_human`	Waiting for a person to act	No
`success`	Finished without errors	Yes
`failed`	A node failed and the run stopped	Yes
`timeout`	The run timed out	Yes
`stopped`	Someone stopped the run	Yes

Poll every few seconds until the status is one of the finished values. For long runs, poll less often.

Read one node's output

A large node output can be left out of the run response. When that happens, fetch it on its own:

GET /api/executions/{executionId}/nodes/{nodeId}/output

For a node inside a loop, add ?iteration=N to read one iteration.

Get the result straight away instead

If the caller needs the result in the same request, use a Webhook trigger in wait mode instead of the API. The webhook answers when the run finishes, with each run's status and data.

List runs

Across a workspace: GET /api/executions?workspaceId=…. Needs executions:read.

Parameter	Meaning
`workspaceId`	Required
`status`	For example `failed`
`workflowId`	Only runs of one workflow
`startedAt[gte]`, `startedAt[lte]`	Start time range, as ISO 8601 timestamps
`search`	Text search across run data
`errorContains`	Runs whose error contains this text
`limit`, `offset`	Paging. `limit` defaults to 100.
`sortBy`, `sortOrder`	Default `startedAt`, `desc`

This list leaves out node outputs. Fetch a run by ID to get them.

For one workflow: GET /api/workflows/{workflowId}/executions. Add limit (up to 100) and offset to page. Add ?latest=true to get the latest successful run with its node outputs.

As a file: GET /api/executions/export?workspaceId=…&format=csv (or format=json) takes the same filters as the list.

Stop, pause and resume

Each needs executions:write.

Request	Effect
`POST /api/executions/{id}/stop`	Stops the run. The node in flight is interrupted. The status becomes `stopped`.
`POST /api/executions/{id}/pause`	Pauses the run
`POST /api/executions/{id}/resume`	Resumes a run you paused

Resume does not answer approvals. Use the approvals endpoint below.

Rerun

POST /api/executions/{id}/rerun. Needs executions:write.

Starts a new run with the original run's trigger data. Returns 202 with the new executionId.

Status	When
`422`	The original run has not finished, or its trigger data is no longer available
`503`	The rerun could not be queued. Try again.

Answer approvals

List waiting runs: GET /api/approvals?workspaceId=…. Needs approvals:read.

Decide: POST /api/approvals/submit. Needs approvals:write.

{
  "executionId": "…",
  "nodeId": "…",
  "approved": true,
  "comment": "Budget confirmed"
}

Field	Meaning
`executionId`, `nodeId`	The waiting run and its approval node. In the list response they are each item's `id` and `currentNodeId`.
`approved`	`true` to approve, `false` to reject
`decision`	Instead of `approved`: the name of the choice, for example `approved` or `rejected`
`comment`	Optional note, kept with the decision

The run continues from the approval node. A 400 means the run is not waiting for input. A 503 means the decision was recorded but the run could not be resumed yet. Submit again.

Found something out of date? This page lives in the Flero docs content set.