Flow runs
Runs are executions of flows. The typical workflow: discover a flow, inspect its required inputs, upload any necessary assets, create a run with matching inputs, poll its status, and retrieve generated outputs once complete. App executions live under App Runs.
Create, monitor, and cancel flow executions.
List flow execution runs with filtering options.
This endpoint returns a paginated list of the organization's flow execution runs, newest first, with their current status and basic metadata. App runs are listed separately via GET /app-runs.
Filtering Options:
status: Filter by execution status (in_progress, completed, failed, canceled). Runs paused on a human review arein_progress.external_id: Filter to runs you tagged with this reference id at creation. Use this to check whether you already started a run for a given item before starting another. A key held by an app run is found viaGET /app-runs.
Pagination Parameters:
limit: Maximum number of items to return (default: 20, min: 1, max: 100)cursor: Pass the previous page'snext_cursorunchanged to get the next page
Response:
data: List of run summaries with basic information (no inputs, results, or pending reviews — fetchGET /runs/{run_id}for those)has_more: Indicates if there are more results availablenext_cursor: Cursor for the next page of results; null on the last page
Use Case: Monitor multiple executions and their status overview.
Error Codes:
401/403/429: Authentication, organization access, or rate limit422: Invalidstatusvalue, orlimitoutside 1–100
API key for authentication
Only return runs in this status
Only return the run created with this external_id (exact match; at most one run, since keys are unique per organization)
Maximum number of items to return
20Cursor for pagination (from next_cursor)
Active organization ID for multi-org support
Successful Response
Validation error (validation_error)
GET /api/public/v1/runs/ HTTP/1.1
X-Api-Key: YOUR_API_KEY
Accept: */*
{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"flow_id": "123e4567-e89b-12d3-a456-426614174000",
"external_id": "text",
"status": "in_progress",
"progress": 0,
"awaiting_human_review": false,
"created_at": "2026-01-01T00:00:00.000Z",
"started_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"cost": 1
}
],
"has_more": true,
"next_cursor": "text"
}Create and start a new flow execution run.
This endpoint launches the execution of a flow with the provided inputs. The execution runs asynchronously, allowing you to monitor progress and retrieve results when complete.
The run executes the flow's last saved version. The flow builder autosaves your edits as a private draft, and drafts never run here — save the flow to put your latest changes behind the API.
Idempotency with external_id: Optionally pass an external_id (e.g. your own order or job id). It is unique per organization: the first request with a given key starts the run; any later write reusing that key — including a dropped-response retry — is rejected with 409 conflict instead of starting (and charging) a duplicate. To fetch the run a key already created, use GET /runs?external_id=.... The id is echoed on every run response.
Scope: per organization, across all runs (flow and app share the key space) and all statuses — a key, once used, stays used.
On
409, do not keep retrying the create;GET /runs?external_id=to retrieve the existing run (orGET /app-runs?external_id=if an app run holds the key). To start a genuinely new run, use a newexternal_id.
How to Build Inputs:
First, get flow details: Call
GET /flows/{flow_id}to retrieve the flow configurationExamine the
inputsarray: Each object defines what input the flow expects:id: Use this as theidin your input objecttype: Determines the input format (see below)description: Explains what this input doesrequired: Whether the run is rejected without it. An omitted optional input runs with the value saved in the flow.
Format inputs based on type —
typeis always one of the five below:
Text Inputs (text_input type) — a string, or a list of strings:
{
"id": "text_input_node_id",
"value": "Your text content here"
}Asset Inputs (image_input, video_input, audio_input, file_input types):
Note: Upload assets first via POST /assets/upload to get the UUIDs. A bare list of asset UUIDs is accepted as value too.
Nothing else in a flow can be set per run: brand (Brain) content and fonts are part of the saved flow, never listed in inputs.
Complete Example Workflow:
Get flow configuration:
Upload assets if needed:
Create run with matching inputs:
Response:
201with the Run object:statusisin_progress, andinputsechoes the requestUse
idfield to monitor progress viaGET /runs/{run_id}Credits are checked once execution starts: a run the organization cannot afford ends
failedwithfailure_reasoninsufficient_credits, not as an error on this call
Running an app instead? Apps have their own surface — use POST /app-runs with an app_id. App runs pause on human review too, and are resolved via POST /app-runs/{run_id}/reviews/{review_id}. See the Apps and App Runs sections.
Error Codes:
400: An inputidthe flow doesn't have, a missing required input, an asset input withoutasset_ids, a flow with configuration errors, or a flow that has never been saved and so has no version to run401: Missing or invalid API key / Bearer token403:X-Organization-Idnames an organization you can't act in404: Flow not found or not accessible409:external_idis already used by a run in this organization422: Malformed body (e.g.flow_idnot a UUID,external_idover 255 characters), or input values the flow's nodes would reject before running429: Rate limit exceeded — retry after theRetry-Afterheader
API key for authentication
Active organization ID for multi-org support
Request to create and start a new flow execution run.
ID of the flow to execute. The former name agent_id is still accepted, and is removed 31 December 2026.
Optional client-supplied reference id (e.g. your order or job id, max 255 chars; longer → 422). Unique per organization across runs and app runs: reusing one returns 409 conflict — so a dropped-response retry never creates a duplicate. Echoed on every run and filterable via GET /runs?external_id= (or GET /app-runs?external_id= when an app run holds it). Use a new id per run.
Successful Response
Complete representation of a flow execution run.
status starts at in_progress and ends at completed, failed or
canceled. A run paused on a human review stays in_progress, with
awaiting_human_review true.
Unique run identifier
ID of the flow being executed
Client-supplied reference id provided at creation, if any
Current execution state: in_progress until the run ends, then completed, failed, or canceled. Stays in_progress while paused on a human review.
Rough completion indicator from 0.0 to 1.0: the share of the nodes started so far that have finished, so it can move backwards as new nodes start. 1.0 when completed; 0.0 when failed or canceled.
0Type of a node currently executing (e.g. image_generation, llm, or human_review while paused on a review). Null unless status is in_progress.
True when the run has paused on one or more human review nodes and is waiting for a decision via POST /runs/{run_id}/reviews/{review_id}. While true, status remains in_progress.
falseWhen the run was created
When execution started
When the run ended (completed, failed, or canceled). Null while in_progress.
Credits consumed so far, summed over the run's nodes. Grows while the run is in progress; null before any node has started.
Error message when the run failed or was canceled. Null otherwise.
Categorized failure reason (timeout, content_policy, insufficient_credits, invalid_input, provider_error, provider_auth_required, canceled, unknown). Present when status is failed or canceled (canceled for a user cancellation); null otherwise.
Deprecated alias for flow_id, removed 31 December 2026.
Validation error (validation_error)
POST /api/public/v1/runs/ HTTP/1.1
X-Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 165
{
"external_id": "order-4821",
"flow_id": "550e8400-e29b-41d4-a716-446655440000",
"inputs": [
{
"id": "text_input_1",
"value": "Create a marketing banner for a tech startup"
}
]
}{
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"awaiting_human_review": false,
"created_at": "2026-04-15T10:00:00Z",
"current_node": "image_generation",
"external_id": "order-4821",
"flow_id": "550e8400-e29b-41d4-a716-446655440000",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"inputs": [
{
"id": "text_input_1",
"value": "A futuristic city at sunset"
}
],
"pending_reviews": [],
"progress": 0.5,
"results": [],
"started_at": "2026-04-15T10:00:01Z",
"status": "in_progress"
}Get detailed information about a specific flow execution run.
This endpoint retrieves comprehensive information about an execution run, including real-time status, progress, inputs, and results when available.
Monitoring Workflow:
Create run via
POST /runsPoll this endpoint to monitor progress
If
awaiting_human_reviewbecomestrue, inspectpending_reviewsand resolve each viaPOST /runs/{run_id}/reviews/{review_id}to resume execution. A review left undecided for a week cancels the run (failure_reason: timeout).Stop polling when status becomes "completed", "failed", or "canceled"
Extract results from the
resultsarray when status is "completed"
Status Lifecycle:
in_progress: Executing, or paused on a human reviewcompleted: Every node finishedfailed: A node failed, or credits ran out. Nodes that finished first keep theirresults, so they can be partialcanceled: Stopped viaDELETE /runs/{run_id}
Progress Tracking:
status: Current execution stateprogress: Rough completion indicator (0.0 to 1.0)current_node: Type of a node currently executing (human_reviewwhile paused on a review); null once the run has endedawaiting_human_review:truewhen the run is paused on a human review node;statusstaysin_progressin this casepending_reviews: List of review steps awaiting a decisioncreated_at/started_at: When the run was created / started executingcompleted_at: When the run ended (if applicable)
How to Retrieve Results:
When the run status becomes "completed", the results array contains the flow outputs. Call GET /flows/{flow_id} and examine the outputs array to understand what results to expect, then match results to outputs by id. results also carries intermediate nodes' outputs — ignore the ids you don't need.
Text Results (type text): value is a string, or a list of strings.
Asset Results (images, videos, audio): value is an array of asset UUIDs. Resolve each via GET /assets/{id} and fetch the url field.
Data Results (data): value is the node's raw output object.
Cost Information:
cost: Credits consumed so far; final once the run has ended
Error Handling:
error: Error message if the run failed or was canceledfailure_reason: Categorized cause, set when the run failed or was canceled
Error Codes:
401/403/429: Authentication, organization access, or rate limit404: Run not found or not accessible — including app runs, which are read viaGET /app-runs/{run_id}422:run_idis not a UUID
API key for authentication
ID of a flow run, from POST /runs or GET /runs. App runs are not found here; use /app-runs/{run_id}.
Active organization ID for multi-org support
Successful Response
Complete representation of a flow execution run.
status starts at in_progress and ends at completed, failed or
canceled. A run paused on a human review stays in_progress, with
awaiting_human_review true.
Unique run identifier
ID of the flow being executed
Client-supplied reference id provided at creation, if any
Current execution state: in_progress until the run ends, then completed, failed, or canceled. Stays in_progress while paused on a human review.
Rough completion indicator from 0.0 to 1.0: the share of the nodes started so far that have finished, so it can move backwards as new nodes start. 1.0 when completed; 0.0 when failed or canceled.
0Type of a node currently executing (e.g. image_generation, llm, or human_review while paused on a review). Null unless status is in_progress.
True when the run has paused on one or more human review nodes and is waiting for a decision via POST /runs/{run_id}/reviews/{review_id}. While true, status remains in_progress.
falseWhen the run was created
When execution started
When the run ended (completed, failed, or canceled). Null while in_progress.
Credits consumed so far, summed over the run's nodes. Grows while the run is in progress; null before any node has started.
Error message when the run failed or was canceled. Null otherwise.
Categorized failure reason (timeout, content_policy, insufficient_credits, invalid_input, provider_error, provider_auth_required, canceled, unknown). Present when status is failed or canceled (canceled for a user cancellation); null otherwise.
Deprecated alias for flow_id, removed 31 December 2026.
Validation error (validation_error)
GET /api/public/v1/runs/{run_id} HTTP/1.1
X-Api-Key: YOUR_API_KEY
Accept: */*
{
"agent_id": "550e8400-e29b-41d4-a716-446655440000",
"awaiting_human_review": false,
"created_at": "2026-04-15T10:00:00Z",
"current_node": "image_generation",
"external_id": "order-4821",
"flow_id": "550e8400-e29b-41d4-a716-446655440000",
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"inputs": [
{
"id": "text_input_1",
"value": "A futuristic city at sunset"
}
],
"pending_reviews": [],
"progress": 0.5,
"results": [],
"started_at": "2026-04-15T10:00:01Z",
"status": "in_progress"
}Cancel an ongoing flow execution run.
This endpoint stops a run whose status is in_progress — including one paused on a human review. Once cancelled, the execution cannot be resumed.
Behavior:
Only
in_progressruns can be cancelled204means cancellation was requested;statusbecomescanceleda few seconds later, withfailure_reasoncanceledNodes that already finished keep their
results, and credits they consumed stay incostPending reviews can no longer be submitted (
409)App runs are cancelled via
DELETE /app-runs/{run_id}
Error Codes:
401/403/429: Authentication, organization access, or rate limit404: Run not found or not accessible, an app run, or a run that is no longerin_progress(completed, failed, or already canceled) — so a repeated cancel returns404422:run_idis not a UUID
API key for authentication
ID of a flow run, from POST /runs or GET /runs. App runs are not found here; use /app-runs/{run_id}.
Active organization ID for multi-org support
Successful Response
No content
Validation error (validation_error)
DELETE /api/public/v1/runs/{run_id} HTTP/1.1
X-Api-Key: YOUR_API_KEY
Accept: */*
No content
Resolve a pending human review and resume an execution.
When a flow includes a human review step, the run pauses on that node and awaiting_human_review becomes true on GET /runs/{run_id} (and has_human_review is true on the flow). Each waiting step is listed in the run's pending_reviews array, and status stays in_progress. Submit a decision here to resume. A review left undecided for one week fails the run.
This endpoint serves flow runs only. App runs pause the same way; resolve theirs via POST /app-runs/{run_id}/reviews/{review_id}.
Discovering pending reviews
Poll
GET /runs/{run_id}untilawaiting_human_reviewistrue.Inspect the
pending_reviewsarray. Use a review'sidasreview_idin this endpoint's path.The
proposed_outputfield of each review is what the upstream node generated. Submit it back asoutput(optionally edited) to approve.
Decisions
approve: continue execution. Theoutputbody field is required and must match the shape ofproposed_output:Image / video / audio reviews:
{"asset_ids": ["..."]}.Text reviews:
{"prompts": ["..."]}(the reviewed node's own text key, as seen inproposed_output, is accepted too). To discard items, approve with only the ones you want to keep — omitted items are dropped. At least one item must be kept (an emptyoutputis rejected with400).
retry: re-run the upstream node(s) to produce a new candidate output.outputis ignored. The review keeps itsidand stays inpending_reviews; itsproposed_outputis null while the upstream node regenerates, then shows the new candidate — decide again once it does.can_generate_moretells you whether the flow offers this; the API acceptsretryregardless.
A 204 means the decision was delivered; poll GET /runs/{run_id} to follow the run from there.
Examples
Approve an image review using the proposed assets:
{
"decision": "approve",
"output": {
"asset_ids": [
"asset-uuid-001",
"asset-uuid-002"
]
}
}Discard some of the proposed assets by approving with only the kept subset:
Retry to regenerate the upstream output:
Error Codes:
400: Missingoutput, an emptyoutput(nothing kept), or anoutputwhose shape doesn't match the review, when decision isapprove.401/403/429: Authentication, organization access, or rate limit.404: Run not found (app runs included — see above), or no human review with that ID on this run.409: The review is no longer waiting (already submitted, or the run finished/failed/was canceled). Checked before the review ID, so anyreview_idon an ended run returns409.422: Malformed body (e.g. adecisionother thanapprove/retry), or a path ID that is not a UUID.
API key for authentication
ID of a flow run, from POST /runs or GET /runs. App runs are not found here; use /app-runs/{run_id}.
id of an entry in the run's pending_reviews
Active organization ID for multi-org support
Request to resolve a pending human review.
approve resumes execution using the (optionally edited) output. retry re-runs the upstream node(s) to produce a new candidate output, then waits for another decision on the same review.
Output to use when continuing execution. Required when decision is approve (missing → 400). Ignored when decision is retry. Must be an object matching the shape of proposed_output ({"asset_ids": [...]} for image/video/audio reviews, {"prompts": [...]} for text reviews — a text node's own key such as texts is also accepted); a mismatched shape is rejected with 400. To discard items, submit only the ones you want to keep; the rest are dropped. At least one item is required — an empty output is rejected with 400.
Successful Response
No content
Validation error (validation_error)
POST /api/public/v1/runs/{run_id}/reviews/{review_id} HTTP/1.1
X-Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 81
{
"decision": "approve",
"output": {
"asset_ids": [
"asset-uuid-001",
"asset-uuid-002"
]
}
}No content
Last updated

