Flow Runs

Execute saved flows programmatically and track multi-step orchestration runs.

Requires API key scopes flows:read (list, get, stream), flows:execute (create, cancel), or flows:write (update, visibility, clone). Create keys in settings → workspace → api keys.

→ Flows concept — how flows chain apps and relate to tasks

Create flow run

POST /flowruns

Starts a new run of a saved flow. Requires flows:execute.

Version selection

The server picks which flow version to run:

1. The published version, when the flow has one (published_version_id is set on GET /flows/{id})
2. The draft version otherwise

The run's flow_version_id is the ID of the version that ran. Compare it with published_version_id and draft_version_id on the flow.

Graph edits made with POST /flows/{id}/actions apply to the draft. When a published version exists, POST /flowruns and belt flow run run it and ignore unpublished draft edits.

→ Flows API: Get flow

Request

Example:

1{2  "flow": "flow_abc123",3  "input": {4    "prompt": "A mountain landscape"5  }6}

Response

Returns a FlowRun object. Key fields:

Example:

1curl -X POST https://api.inference.sh/flowruns \2  -H "Authorization: Bearer inf_your_key" \3  -H "Content-Type: application/json" \4  -d '{"flow":"flow_abc123","input":{"prompt":"A mountain landscape"}}'

JavaScript SDK

1const run = await client.flowRuns.create('flow_abc123', { prompt: 'A mountain landscape' });2console.log(run.task_id, run.status);

CLI equivalent: belt flow run <flow-id> --input '{"prompt":"A mountain landscape"}' (add -f to stream progress until complete).

The Python SDK does not yet expose flowRuns; use the REST call above.

Get flow run

GET /flowruns/{id}

Returns a single flow run by ID. Same fields as the create response, plus node_statuses (see Per-node progress).

1curl https://api.inference.sh/flowruns/flowrun_abc123 \2  -H "Authorization: Bearer inf_your_key"

CLI equivalent: belt flow run-get <run-id> (add -f to follow until complete).

List flow runs

POST /flowruns/list

Cursor-paginated list. Requires flows:read.

GET /flowruns is also available with the same scope.

Cancel flow run

POST /flowruns/{id}/cancel

Stops an in-progress flow run. Requires flows:execute.

1curl -X POST https://api.inference.sh/flowruns/flowrun_abc123/cancel \2  -H "Authorization: Bearer inf_your_key"

Clone flow from a run

POST /flowruns/{id}/clone

Creates a new flow definition copied from the flow version used in this run. Returns a Flow object (not a new run). Requires flows:write.

Use this to fork a flow after iterating in the editor or from a successful run.

Update flow run

POST /flowruns/{id}

Patch flow run metadata. Requires flows:write.

POST /flowruns/{id}/visibility updates sharing visibility.

Stream updates

Real-time SSE for flow run state and per-step tasks.

Send Accept: text/event-stream. Event format matches Task streaming.

JavaScript SDK

1const source = client.flowRuns.stream('flowrun_abc123');2const taskSource = client.flowRuns.streamTasks('flowrun_abc123');

→ Streaming API

Per-node progress

A flow run reports step progress in three fields:

node_statuses is filled in only by GET /flowruns/{id}. It is omitted from create and list responses. node_outputs is stored on the flow run and is null until a utility node stores a result. Keys in all three maps are flow node IDs from the flow definition.

Each node_outputs entry is an object with a value field.

Example fragment:

1{2  "node_tasks": {3    "generate": { "task_id": "task_abc123" }4  },5  "node_statuses": {6    "input": "completed",7    "generate": "running",8    "gate_1": "failed",9    "selector_1": "completed",10    "upscale": "blocked"11  },12  "node_outputs": {13    "selector_1": { "value": "first_item" },14    "constant_1": { "value": "hello" }15  }16}

Graph node status values

A gate whose condition is false is reported as failed, and the nodes that depend on it as blocked. A failed gate does not fail the run. See Flows API: Gate nodes.

JavaScript SDK

1import { GraphNodeStatusFailed, GraphNodeStatusRunning } from '@inferencesh/sdk';23const { data: run } = await client.flowRuns.get('flowrun_abc123');45if (run.node_statuses?.gate_1 === GraphNodeStatusFailed) {6  console.log('Gate condition was false');7}8if (run.node_statuses?.generate === GraphNodeStatusRunning) {9  console.log('Still running:', run.node_tasks.generate?.task_id);10}11console.log(run.node_outputs?.selector_1?.value);

Flow run status codes

Flow runs use a separate status enum from task status codes.

The parent task_id on the flow run tracks overall progress in the Tasks API and the web app.

Related

→ Tasks API — parent task status, logs, cost, cancellation
→ Flows — visual editor, deploying flows as apps
→ REST overview — authentication and response format