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 → 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.
Request
| Field | Type | Required | Description |
|---|---|---|---|
flow | string | Yes | Flow ID |
input | object | Yes | Flow inputs (shape depends on the flow definition) |
Example:
1{2 "flow": "flow_abc123",3 "input": {4 "prompt": "A mountain landscape"5 }6}Response
Returns a FlowRun object. Key fields:
| Field | Type | Description |
|---|---|---|
id | string | Flow run ID |
flow_id | string | Source flow ID |
flow_version_id | string | Flow version used for this run |
task_id | string | Parent task ID (tracks the full run in Tasks) |
status | number | Flow run status code (see below) |
input | object | Inputs passed to the run |
output | object | Final output when complete |
node_tasks | object | Per-node task references (task_id, nested task) |
error | string | Error message when failed |
flow_run_started | string | ISO timestamp when execution began |
flow_run_finished | string | ISO timestamp when execution completed |
Example:
1curl -X POST https://api.inference.sh/flowruns \2 -H "Authorization: Bearer inf_your_key" \3 -H "Content-Type: application/json" \4 -H "X-API-Version: 2" \5 -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);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 create response.
1curl https://api.inference.sh/flowruns/flowrun_abc123 \2 -H "Authorization: Bearer inf_your_key" \3 -H "X-API-Version: 2"List flow runs
POST /flowruns/list
Cursor-paginated list. Requires flows:read.
GET /flowruns is also available with the same scope.
| Field | Type | Description |
|---|---|---|
limit | number | Page size |
cursor | string | Cursor from a previous response |
filters | array | Filter objects (field, operator, value) |
sort | array | Sort objects (field, dir) |
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" \3 -H "X-API-Version: 2"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.
| Endpoint | Scope | Description |
|---|---|---|
GET /flowruns/{id}/stream | flows:read | Flow run status and output updates |
GET /flowruns/{id}/tasks/stream | flows:read | Task updates for nodes in this run |
Send Accept: text/event-stream and X-API-Version: 2. Event format matches Task streaming.
JavaScript SDK
1const source = client.flowRuns.stream('flowrun_abc123');2const taskSource = client.flowRuns.streamTasks('flowrun_abc123');Flow run status codes
Flow runs use a separate status enum from task status codes.
| Status | Code | Description |
|---|---|---|
| Unknown | 0 | Unrecognized status |
| Pending | 1 | Starting |
| Running | 2 | Executing steps |
| Completed | 3 | Done |
| Failed | 4 | Error occurred |
| Cancelled | 5 | Cancelled |
The parent task_id on the flow run tracks overall progress in the Tasks API and workspace UI.
Related
→ Tasks API — parent task status, logs, cost, cancellation
→ Flows — visual editor, deploying flows as apps
→ REST overview — authentication and API versioning