Starting runs

Any workflow you can run in the app, you can start through the API. The run is the same as one started in the builder: every step is checkpointed and visible on the run page, and it counts once against your plan’s monthly runs. Run history shows API as its starter.

Before you start

• An organization key. An owner or admin creates one on the API keys page. See API keys.
• The workflow’s id. It is the last part of the builder’s address, https://superflows.app/app/workflows/<id>. Through the API, list projects with GET /api/v1/projects, then a project’s workflows with GET /api/v1/projects/{projectId}/workflows.
• A published version. API runs use the live version. Publish in the builder first, or run the draft with "draft": true. See Versions and publishing.

Start a run

curl -X POST https://superflows.app/api/v1/workflows/WORKFLOW_ID/runs \
  -H "Authorization: Bearer sf_..." \
  -H "Content-Type: application/json" \
  -d '{"input": "{\"customer\": \"Ada\", \"subject\": \"Refund request\"}"}'

The body has three fields, all optional:

Field	Type	Default	What it does
input	string	""	The trigger’s payload, up to 100,000 characters
draft	boolean	false	Runs the draft instead of the live version
triggerNodeId	string	none	The Trigger node to start from. Required when the workflow has more than one

input is a string. To send structured data, put JSON text in it, as above. Steps then read its fields as {{ trigger.customer }} or {{ trigger.subject }}. Text that is not JSON reaches the steps as plain text. See Templates and variables.

With no body at all, the run starts the live version from its only trigger with an empty payload.

An API run can start from any Trigger node, whatever its kind. A paused workflow still accepts API runs: pausing turns off only its schedule and app event triggers.

Read the result

The call answers 201 with the run as soon as it starts, usually before its steps finish. Keep its id and poll the run until status is complete, errored or terminated:

curl https://superflows.app/api/v1/runs/RUN_ID \
  -H "Authorization: Bearer sf_..."

Field	What it holds
status	queued, running, waiting, paused, complete, errored or terminated, among others
version	The published version it ran, or null for a draft run
trigger	api for a run started with a key
reply	The text of the steps the run ended on
error	The error message when the run failed
steps	Each step it reached, in order: nodeId, status, input, output, error, ms

A step’s status is running, waiting, done, error or skipped. Its output holds each field as {{ nodes.<nodeId>.<field> }} reads it.

Each poll counts against the key’s 1,000 requests an hour, so poll every few seconds. A run whose Agent step waits for an approval can stay unfinished for up to 72 hours. See Talking to agents for deciding approvals from code.

Super Flows keeps a run’s live status for 30 days. After that, the run’s status reads unknown, and its steps are still there.

List a workflow’s runs

curl "https://superflows.app/api/v1/workflows/WORKFLOW_ID/runs?limit=20" \
  -H "Authorization: Bearer sf_..."

Runs come newest first in data. Pass the response’s nextCursor as cursor to get the next page, until nextCursor is null. limit is 1 to 100, 20 by default.

Errors

Status	Code	What to do
404	workflow_not_found	Check the id and that the key belongs to the workflow’s organization
409	not_published	Publish the workflow, or send "draft": true
400	invalid_workflow	The diagram cannot run. The message says why
400	trigger_required	The workflow has several triggers. details.triggers lists each id and label
400	invalid_request	The body failed validation. details.issues lists each problem
402	plan_limit_reached	The month’s runs are used up. See Allowances

A run that starts and then fails is not an API error. The call succeeds, and the run’s status becomes errored with the failing step’s error set.