For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 Runs

get

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 are in_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 via GET /app-runs.

Pagination Parameters:

  • limit: Maximum number of items to return (default: 20, min: 1, max: 100)

  • cursor: Pass the previous page's next_cursor unchanged to get the next page

Response:

  • data: List of run summaries with basic information (no inputs, results, or pending reviews — fetch GET /runs/{run_id} for those)

  • has_more: Indicates if there are more results available

  • next_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 limit

  • 422: Invalid status value, or limit outside 1–100

Authorizations
X-Api-KeystringRequired

API key for authentication

Query parameters
statusstring · enum · nullableOptional

Only return runs in this status

Possible values:
external_idstring · nullableOptional

Only return the run created with this external_id (exact match; at most one run, since keys are unique per organization)

limitinteger · min: 1 · max: 100Optional

Maximum number of items to return

Default: 20
cursorstring · nullableOptional

Cursor for pagination (from next_cursor)

Header parameters
X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses
200

Successful Response

application/json
has_morebooleanRequired
next_cursorstring · nullableOptional
get/v1/runs/
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 Run

post

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 (or GET /app-runs?external_id= if an app run holds the key). To start a genuinely new run, use a new external_id.

How to Build Inputs:

  1. First, get flow details: Call GET /flows/{flow_id} to retrieve the flow configuration

  2. Examine the inputs array: Each object defines what input the flow expects:

    • id: Use this as the id in your input object

    • type: Determines the input format (see below)

    • description: Explains what this input does

    • required: Whether the run is rejected without it. An omitted optional input runs with the value saved in the flow.

  3. Format inputs based on type — type is 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:

  1. Get flow configuration:

  1. Upload assets if needed:

  1. Create run with matching inputs:

Response:

  • 201 with the Run object: status is in_progress, and inputs echoes the request

  • Use id field to monitor progress via GET /runs/{run_id}

  • Credits are checked once execution starts: a run the organization cannot afford ends failed with failure_reason insufficient_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 input id the flow doesn't have, a missing required input, an asset input without asset_ids, a flow with configuration errors, or a flow that has never been saved and so has no version to run

  • 401: Missing or invalid API key / Bearer token

  • 403: X-Organization-Id names an organization you can't act in

  • 404: Flow not found or not accessible

  • 409: external_id is already used by a run in this organization

  • 422: Malformed body (e.g. flow_id not a UUID, external_id over 255 characters), or input values the flow's nodes would reject before running

  • 429: Rate limit exceeded — retry after the Retry-After header

Authorizations
X-Api-KeystringRequired

API key for authentication

Header parameters
X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Body

Request to create and start a new flow execution run.

flow_idstring · uuidRequired

ID of the flow to execute. The former name agent_id is still accepted, and is removed 31 December 2026.

external_idstring · max: 255 · nullableOptional

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.

Responses
201

Successful Response

application/json

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.

idstring · uuidRequired

Unique run identifier

flow_idstring · uuidRequired

ID of the flow being executed

external_idstring · nullableOptional

Client-supplied reference id provided at creation, if any

statusstring · enumRequired

Current execution state: in_progress until the run ends, then completed, failed, or canceled. Stays in_progress while paused on a human review.

Possible values:
progressnumber · max: 1Optional

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.

Default: 0
current_nodestring · nullableOptional

Type of a node currently executing (e.g. image_generation, llm, or human_review while paused on a review). Null unless status is in_progress.

awaiting_human_reviewbooleanOptional

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.

Default: false
created_atstring · date-timeRequired

When the run was created

started_atstring · date-time · nullableOptional

When execution started

completed_atstring · date-time · nullableOptional

When the run ended (completed, failed, or canceled). Null while in_progress.

costinteger · nullableOptional

Credits consumed so far, summed over the run's nodes. Grows while the run is in progress; null before any node has started.

errorstring · nullableOptional

Error message when the run failed or was canceled. Null otherwise.

failure_reasonstring · enum · nullableOptional

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.

Possible values:
agent_idstring · uuidRead-onlyRequiredDeprecated

Deprecated alias for flow_id, removed 31 December 2026.

post/v1/runs/
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 Run

get

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:

  1. Create run via POST /runs

  2. Poll this endpoint to monitor progress

  3. If awaiting_human_review becomes true, inspect pending_reviews and resolve each via POST /runs/{run_id}/reviews/{review_id} to resume execution. A review left undecided for a week cancels the run (failure_reason: timeout).

  4. Stop polling when status becomes "completed", "failed", or "canceled"

  5. Extract results from the results array when status is "completed"

Status Lifecycle:

  • in_progress: Executing, or paused on a human review

  • completed: Every node finished

  • failed: A node failed, or credits ran out. Nodes that finished first keep their results, so they can be partial

  • canceled: Stopped via DELETE /runs/{run_id}

Progress Tracking:

  • status: Current execution state

  • progress: Rough completion indicator (0.0 to 1.0)

  • current_node: Type of a node currently executing (human_review while paused on a review); null once the run has ended

  • awaiting_human_review: true when the run is paused on a human review node; status stays in_progress in this case

  • pending_reviews: List of review steps awaiting a decision

  • created_at / started_at: When the run was created / started executing

  • completed_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 canceled

  • failure_reason: Categorized cause, set when the run failed or was canceled

Error Codes:

  • 401 / 403 / 429: Authentication, organization access, or rate limit

  • 404: Run not found or not accessible — including app runs, which are read via GET /app-runs/{run_id}

  • 422: run_id is not a UUID

Authorizations
X-Api-KeystringRequired

API key for authentication

Path parameters
run_idstring · uuidRequired

ID of a flow run, from POST /runs or GET /runs. App runs are not found here; use /app-runs/{run_id}.

Header parameters
X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses
200

Successful Response

application/json

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.

idstring · uuidRequired

Unique run identifier

flow_idstring · uuidRequired

ID of the flow being executed

external_idstring · nullableOptional

Client-supplied reference id provided at creation, if any

statusstring · enumRequired

Current execution state: in_progress until the run ends, then completed, failed, or canceled. Stays in_progress while paused on a human review.

Possible values:
progressnumber · max: 1Optional

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.

Default: 0
current_nodestring · nullableOptional

Type of a node currently executing (e.g. image_generation, llm, or human_review while paused on a review). Null unless status is in_progress.

awaiting_human_reviewbooleanOptional

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.

Default: false
created_atstring · date-timeRequired

When the run was created

started_atstring · date-time · nullableOptional

When execution started

completed_atstring · date-time · nullableOptional

When the run ended (completed, failed, or canceled). Null while in_progress.

costinteger · nullableOptional

Credits consumed so far, summed over the run's nodes. Grows while the run is in progress; null before any node has started.

errorstring · nullableOptional

Error message when the run failed or was canceled. Null otherwise.

failure_reasonstring · enum · nullableOptional

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.

Possible values:
agent_idstring · uuidRead-onlyRequiredDeprecated

Deprecated alias for flow_id, removed 31 December 2026.

get/v1/runs/{run_id}
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 Run

delete

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_progress runs can be cancelled

  • 204 means cancellation was requested; status becomes canceled a few seconds later, with failure_reason canceled

  • Nodes that already finished keep their results, and credits they consumed stay in cost

  • Pending 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 limit

  • 404: Run not found or not accessible, an app run, or a run that is no longer in_progress (completed, failed, or already canceled) — so a repeated cancel returns 404

  • 422: run_id is not a UUID

Authorizations
X-Api-KeystringRequired

API key for authentication

Path parameters
run_idstring · uuidRequired

ID of a flow run, from POST /runs or GET /runs. App runs are not found here; use /app-runs/{run_id}.

Header parameters
X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses
204

Successful Response

No content

delete/v1/runs/{run_id}
DELETE /api/public/v1/runs/{run_id} HTTP/1.1
X-Api-Key: YOUR_API_KEY
Accept: */*

No content

Submit Review

post

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

  1. Poll GET /runs/{run_id} until awaiting_human_review is true.

  2. Inspect the pending_reviews array. Use a review's id as review_id in this endpoint's path.

  3. The proposed_output field of each review is what the upstream node generated. Submit it back as output (optionally edited) to approve.

Decisions

  • approve: continue execution. The output body field is required and must match the shape of proposed_output:

    • Image / video / audio reviews: {"asset_ids": ["..."]}.

    • Text reviews: {"prompts": ["..."]} (the reviewed node's own text key, as seen in proposed_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 empty output is rejected with 400).

  • retry: re-run the upstream node(s) to produce a new candidate output. output is ignored. The review keeps its id and stays in pending_reviews; its proposed_output is null while the upstream node regenerates, then shows the new candidate — decide again once it does. can_generate_more tells you whether the flow offers this; the API accepts retry regardless.

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: Missing output, an empty output (nothing kept), or an output whose shape doesn't match the review, when decision is approve.

  • 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 any review_id on an ended run returns 409.

  • 422: Malformed body (e.g. a decision other than approve/retry), or a path ID that is not a UUID.

Authorizations
X-Api-KeystringRequired

API key for authentication

Path parameters
run_idstring · uuidRequired

ID of a flow run, from POST /runs or GET /runs. App runs are not found here; use /app-runs/{run_id}.

review_idstring · uuidRequired

id of an entry in the run's pending_reviews

Header parameters
X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Body

Request to resolve a pending human review.

decisionstring · enumRequired

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.

Possible values:
outputany of · nullableOptional

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.

or
or
stringOptional
Responses
204

Successful Response

No content

post/v1/runs/{run_id}/reviews/{review_id}
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