> For the complete documentation index, see [llms.txt](https://docs.pletor.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pletor.ai/documentation/api-reference/flow-runs.md).

# 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

> 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).\
> &#x20; Runs paused on a human review are \`in\_progress\`.\
> \- \`external\_id\`: Filter to runs you tagged with this reference id at creation.\
> &#x20; Use this to check whether you already started a run for a given item before\
> &#x20; 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,\
> &#x20; 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

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel flow executions."}],"servers":[{"url":"/api/public"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Cognito JWT Bearer token"}},"schemas":{"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."},"CursorPaginatedResponse_RunSummary_":{"properties":{"data":{"items":{"$ref":"#/components/schemas/RunSummary"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"CursorPaginatedResponse[RunSummary]"},"RunSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"flow_id":{"type":"string","format":"uuid","title":"Flow Id","description":"ID of the flow that was executed"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Client-supplied reference id provided at creation, if any"},"status":{"$ref":"#/components/schemas/FlowRunStatus","description":"Current execution state: in_progress, completed, failed, or canceled"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Rough completion indicator from 0.0 to 1.0 (see `Run.progress`)","default":0},"awaiting_human_review":{"type":"boolean","title":"Awaiting Human Review","description":"True when the run has paused on one or more human review nodes. Fetch GET /runs/{run_id} to inspect pending reviews.","default":false},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was created"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution started"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the run ended (completed, failed, or canceled). Null while in_progress."},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Credits consumed so far, summed over the run's nodes; null before any node has started"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"Deprecated alias for `flow_id`, removed 31 December 2026.","deprecated":true,"readOnly":true}},"type":"object","required":["id","flow_id","status","created_at","agent_id"],"title":"RunSummary","description":"Lightweight run summary for list views."},"ApiErrorResponse":{"description":"Standard error response envelope. All API errors follow this format.","properties":{"error":{"$ref":"#/components/schemas/ApiErrorDetail","description":"Error details"}},"required":["error"],"title":"ApiErrorResponse","type":"object"},"ApiErrorDetail":{"description":"Structured details for an API error.","properties":{"code":{"$ref":"#/components/schemas/ApiErrorCode","description":"Machine-readable error code; branch on this, not on `message`"},"message":{"description":"Human-readable error description","title":"Message","type":"string"},"status":{"description":"HTTP status code of this response","title":"Status","type":"integer"},"details":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}]},"description":"Additional context. Always holds `request_id` (the response's `X-Request-Id`); `validation_error` from request validation adds `errors`, a list of `location: message` strings, and `rate_limit_exceeded` adds `retry_after`, the seconds to wait.","title":"Details","type":"object"}},"required":["code","message","status","details"],"title":"ApiErrorDetail","type":"object"},"ApiErrorCode":{"description":"Machine-readable error code, with its usual HTTP status: `invalid_input`\n400, `authentication_required` 401, `forbidden` 403, `not_found` 404,\n`conflict` 409, `validation_error` 422, `rate_limit_exceeded` 429,\n`internal_error` 500, `run_failed` 502, `service_unavailable` 503, `timeout`\n504. A 4xx status without a code of its own is sent as `invalid_input`.\n\n`plan_required`, `credit_usage_exceeded`, `user_quota_exceeded`,\n`spend_limit_exceeded`, `brain_flow_impact`, `stale_definition`,\n`flow_not_shared` and `asset_not_ready` have no status of their own and are\nsent only in the `X-Pletor-Error-Code` response header, never as `code`.","enum":["invalid_input","authentication_required","forbidden","not_found","conflict","validation_error","rate_limit_exceeded","internal_error","run_failed","service_unavailable","timeout","plan_required","credit_usage_exceeded","user_quota_exceeded","spend_limit_exceeded","brain_flow_impact","stale_definition","flow_not_shared","asset_not_ready"],"title":"ApiErrorCode","type":"string"}}},"paths":{"/v1/runs/":{"get":{"tags":["runs"],"summary":"List Runs","description":"List flow execution runs with filtering options.\n\nThis endpoint returns a paginated list of the organization's flow execution\nruns, newest first, with their current status and basic metadata. App runs\nare listed separately via `GET /app-runs`.\n\n**Filtering Options:**\n- `status`: Filter by execution status (in_progress, completed, failed, canceled).\n  Runs paused on a human review are `in_progress`.\n- `external_id`: Filter to runs you tagged with this reference id at creation.\n  Use this to check whether you already started a run for a given item before\n  starting another. A key held by an app run is found via `GET /app-runs`.\n\n**Pagination Parameters:**\n- `limit`: Maximum number of items to return (default: 20, min: 1, max: 100)\n- `cursor`: Pass the previous page's `next_cursor` unchanged to get the next page\n\n**Response:**\n- `data`: List of run summaries with basic information (no inputs, results,\n  or pending reviews — fetch `GET /runs/{run_id}` for those)\n- `has_more`: Indicates if there are more results available\n- `next_cursor`: Cursor for the next page of results; null on the last page\n\n**Use Case:** Monitor multiple executions and their status overview.\n\n**Error Codes:**\n- `401` / `403` / `429`: Authentication, organization access, or rate limit\n- `422`: Invalid `status` value, or `limit` outside 1–100","operationId":"v1_list_runs_runs__get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/FlowRunStatus"},{"type":"null"}],"description":"Only return runs in this status","title":"Status"},"description":"Only return runs in this status"},{"name":"external_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only return the run created with this `external_id` (exact match; at most one run, since keys are unique per organization)","title":"External Id"},"description":"Only return the run created with this `external_id` (exact match; at most one run, since keys are unique per organization)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of items to return","default":20,"title":"Limit"},"description":"Maximum number of items to return"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Cursor for pagination (from next_cursor)","title":"Cursor"},"description":"Cursor for pagination (from next_cursor)"},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CursorPaginatedResponse_RunSummary_"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}}}
```

## Create Run

> 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\
> &#x20; space) and \*\*all\*\* statuses — a key, once used, stays used.\
> \- On \`409\`, do \*\*not\*\* keep retrying the create; \`GET /runs?external\_id=\` to\
> &#x20; retrieve the existing run (or \`GET /app-runs?external\_id=\` if an app run\
> &#x20; 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:\
> &#x20;  \- \`id\`: Use this as the \`id\` in your input object\
> &#x20;  \- \`type\`: Determines the input format (see below)\
> &#x20;  \- \`description\`: Explains what this input does\
> &#x20;  \- \`required\`: Whether the run is rejected without it. An omitted optional\
> &#x20;    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:\
> \`\`\`json\
> {\
> &#x20;   "id": "text\_input\_node\_id",\
> &#x20;   "value": "Your text content here"\
> }\
> \`\`\`\
> \
> \*\*Asset Inputs\*\* (\`image\_input\`, \`video\_input\`, \`audio\_input\`, \`file\_input\` types):\
> \`\`\`json\
> {\
> &#x20;   "id": "image\_input\_node\_id",\
> &#x20;   "value": {\
> &#x20;       "asset\_ids": \["uuid1", "uuid2"]\
> &#x20;   }\
> }\
> \`\`\`\
> 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:\
> \`\`\`bash\
> GET /flows/550e8400-e29b-41d4-a716-446655440000\
> \# Response shows inputs: \[\
> \#   {"id": "uuid-1", "type": "text\_input", "description": "Product description"},\
> \#   {"id": "uuid-2", "type": "image\_input", "description": "Company logo"}\
> \# ]\
> \`\`\`\
> \
> 2\. Upload assets if needed:\
> \`\`\`bash\
> POST /assets/upload\
> \# Response: {"id": "asset-uuid-123", ...}\
> \`\`\`\
> \
> 3\. Create run with matching inputs:\
> \`\`\`json\
> {\
> &#x20;   "flow\_id": "550e8400-e29b-41d4-a716-446655440000",\
> &#x20;   "inputs": \[\
> &#x20;       {\
> &#x20;           "id": "uuid-1",\
> &#x20;           "value": "Create a marketing banner for a tech startup"\
> &#x20;       },\
> &#x20;       {\
> &#x20;           "id": "uuid-2",\
> &#x20;           "value": {\
> &#x20;               "asset\_ids": \["asset-uuid-123"]\
> &#x20;           }\
> &#x20;       }\
> &#x20;   ]\
> }\
> \`\`\`\
> \
> \*\*Response:\*\*\
> \- \`201\` with the Run object: \`status\` is \`in\_progress\`, and \`inputs\` echoes\
> &#x20; the request\
> \- Use \`id\` field to monitor progress via \`GET /runs/{run\_id}\`\
> \- Credits are checked once execution starts: a run the organization cannot\
> &#x20; afford ends \`failed\` with \`failure\_reason\` \`insufficient\_credits\`, not as an\
> &#x20; 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\
> &#x20; asset input without \`asset\_ids\`, a flow with configuration errors, or a\
> &#x20; 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\
> &#x20; characters), or input values the flow's nodes would reject before running\
> \- \`429\`: Rate limit exceeded — retry after the \`Retry-After\` header

````json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel flow executions."}],"servers":[{"url":"/api/public"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Cognito JWT Bearer token"}},"schemas":{"RunCreateRequest":{"properties":{"flow_id":{"type":"string","format":"uuid","title":"Flow Id","description":"ID of the flow to execute. The former name `agent_id` is still accepted, and is removed 31 December 2026."},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Values for the flow's inputs, as listed in GET /flows/{id}. Each `id` must be one of those inputs (unknown ids → 400), and every input with `required: true` must be present (missing → 400). An omitted optional input runs with the value saved in the flow."},"external_id":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"External Id","description":"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."}},"type":"object","required":["flow_id"],"title":"RunCreateRequest","description":"Request to create and start a new flow execution run."},"RunInput":{"properties":{"id":{"type":"string","title":"Id","description":"ID of the input this value fills, as listed in the `inputs` of the flow or app"},"value":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"title":"Value","description":"Input value. Text inputs take a string, or a list of strings. Image, video, audio and file inputs take {\"asset_ids\": [\"uuid\", ...]} (a bare list of asset IDs is also accepted). Upload files first via POST /assets/upload. When read back from a stored run, text values come back as a list of strings and asset values as {\"asset_ids\": [...]}."}},"type":"object","required":["id","value"],"title":"RunInput","description":"Represents an input provided to a run.\n\nShared by runs and app runs: both pipelines accept the same wire shape."},"Run":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"flow_id":{"type":"string","format":"uuid","title":"Flow Id","description":"ID of the flow being executed"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Client-supplied reference id provided at creation, if any"},"status":{"$ref":"#/components/schemas/FlowRunStatus","description":"Current execution state: `in_progress` until the run ends, then `completed`, `failed`, or `canceled`. Stays `in_progress` while paused on a human review."},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"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_node":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Node","description":"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_review":{"type":"boolean","title":"Awaiting Human Review","description":"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},"pending_reviews":{"items":{"$ref":"#/components/schemas/PendingReview"},"type":"array","title":"Pending Reviews","description":"Human review steps currently waiting for a decision. Empty unless `awaiting_human_review` is true."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was created"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution started"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the run ended (completed, failed, or canceled). Null while in_progress."},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs for this run. The create response echoes the request as sent; later reads return the stored values (text as a list of strings, assets as {\"asset_ids\": [...]})."},"results":{"items":{"$ref":"#/components/schemas/RunResult"},"type":"array","title":"Results","description":"One entry per executed node that produced output — intermediate nodes included, not only the flow's `outputs`; match by `id`. Entries appear as nodes finish, so an in-progress or failed run can carry partial results. After a review `retry`, each node reports its latest output."},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Credits consumed so far, summed over the run's nodes. Grows while the run is in progress; null before any node has started."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message when the run failed or was canceled. Null otherwise."},"failure_reason":{"anyOf":[{"$ref":"#/components/schemas/FailureReason"},{"type":"null"}],"description":"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."},"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"Deprecated alias for `flow_id`, removed 31 December 2026.","deprecated":true,"readOnly":true}},"type":"object","required":["id","flow_id","status","created_at","agent_id"],"title":"Run","description":"Complete representation of a flow execution run.\n\n`status` starts at `in_progress` and ends at `completed`, `failed` or\n`canceled`. A run paused on a human review stays `in_progress`, with\n`awaiting_human_review` true."},"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."},"PendingReview":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Identifier of the pending review. Use this as `review_id` when calling POST /runs/{run_id}/reviews/{review_id} — or POST /app-runs/{run_id}/reviews/{review_id} for an app run — to resume execution. A `retry` keeps the same id: the review stays listed while the upstream output regenerates."},"node_id":{"type":"string","title":"Node Id","description":"ID of the human review node inside the flow definition"},"reviewed_node_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewed Node Type","description":"Type of the upstream node whose output is being reviewed (e.g. image_generation, llm). Null when that node has no execution record — input nodes (text/image/video/audio/file inputs) never do."},"reviewed_output_type":{"anyOf":[{"$ref":"#/components/schemas/DataType"},{"type":"null"}],"description":"Kind of output under review (text, images, videos, audio, data). Null when `reviewed_node_type` is null or has no public output mapping."},"proposed_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"string"},{"type":"null"}],"title":"Proposed Output","description":"Output of the reviewed upstream node (the first one, when the review covers several), in that node's own shape — e.g. {\"asset_ids\": [...]} for media. Submit it back (optionally edited) as `output` when approving. To discard items, submit only the ones you want to keep — omitted items are dropped. At least one item must be kept. Null when there is nothing to show: the review covers only input nodes, or the upstream node is still regenerating after a `retry`."},"can_edit_outputs":{"type":"boolean","title":"Can Edit Outputs","description":"Always true: every review step lets reviewers edit the proposed output.","default":true},"can_generate_more":{"type":"boolean","title":"Can Generate More","description":"Whether the review step offers regenerating the upstream output (decision `retry`). Always false when the review only covers input nodes. Informational: the API does not enforce it.","default":false},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the review was opened"}},"type":"object","required":["id","node_id","created_at"],"title":"PendingReview","description":"A human review step that is currently waiting for a decision.\n\nShared by runs and app runs: both pause on human review nodes the same way."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Kind of content an output, run result or review carries. In run results,\n`text` values are text, `images` / `videos` / `audio` values are asset IDs\nto download, and `data` values are structured JSON."},"RunResult":{"properties":{"id":{"type":"string","title":"Id","description":"ID of the node that produced this result. Match it against the `id` of an entry in the flow's or app's `outputs`."},"type":{"$ref":"#/components/schemas/DataType","description":"Kind of result: `text`, `images`, `videos`, `audio`, or `data` (structured output, and any node type without a more specific mapping)"},"value":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Result content. `text`: a string, or a list of strings when the node produced several. `images` / `videos` / `audio`: a list of asset IDs — resolve each via GET /assets/{id}. `data`: the node's raw output object."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Generic label for the result kind (e.g. \"Generated images\")"}},"type":"object","required":["id","type"],"title":"RunResult","description":"Represents a result produced by a run.\n\nShared by runs and app runs: both pipelines emit the same wire shape."},"FailureReason":{"type":"string","enum":["timeout","content_policy","insufficient_credits","invalid_input","provider_error","provider_auth_required","canceled","unknown"],"title":"FailureReason","description":"Stable category for why a run failed: `timeout` (a step ran out of time),\n`content_policy` (blocked by content moderation), `insufficient_credits`\n(credit or quota exhausted), `invalid_input` (an input, or an uploaded file,\ncould not be used), `provider_error` (an upstream AI provider failed),\n`provider_auth_required` (a connected provider account is missing or expired\nand must be reconnected), `canceled` (the run was canceled), `unknown` (any\ncause without a category of its own)."},"ApiErrorResponse":{"description":"Standard error response envelope. All API errors follow this format.","properties":{"error":{"$ref":"#/components/schemas/ApiErrorDetail","description":"Error details"}},"required":["error"],"title":"ApiErrorResponse","type":"object"},"ApiErrorDetail":{"description":"Structured details for an API error.","properties":{"code":{"$ref":"#/components/schemas/ApiErrorCode","description":"Machine-readable error code; branch on this, not on `message`"},"message":{"description":"Human-readable error description","title":"Message","type":"string"},"status":{"description":"HTTP status code of this response","title":"Status","type":"integer"},"details":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}]},"description":"Additional context. Always holds `request_id` (the response's `X-Request-Id`); `validation_error` from request validation adds `errors`, a list of `location: message` strings, and `rate_limit_exceeded` adds `retry_after`, the seconds to wait.","title":"Details","type":"object"}},"required":["code","message","status","details"],"title":"ApiErrorDetail","type":"object"},"ApiErrorCode":{"description":"Machine-readable error code, with its usual HTTP status: `invalid_input`\n400, `authentication_required` 401, `forbidden` 403, `not_found` 404,\n`conflict` 409, `validation_error` 422, `rate_limit_exceeded` 429,\n`internal_error` 500, `run_failed` 502, `service_unavailable` 503, `timeout`\n504. A 4xx status without a code of its own is sent as `invalid_input`.\n\n`plan_required`, `credit_usage_exceeded`, `user_quota_exceeded`,\n`spend_limit_exceeded`, `brain_flow_impact`, `stale_definition`,\n`flow_not_shared` and `asset_not_ready` have no status of their own and are\nsent only in the `X-Pletor-Error-Code` response header, never as `code`.","enum":["invalid_input","authentication_required","forbidden","not_found","conflict","validation_error","rate_limit_exceeded","internal_error","run_failed","service_unavailable","timeout","plan_required","credit_usage_exceeded","user_quota_exceeded","spend_limit_exceeded","brain_flow_impact","stale_definition","flow_not_shared","asset_not_ready"],"title":"ApiErrorCode","type":"string"}}},"paths":{"/v1/runs/":{"post":{"tags":["runs"],"summary":"Create Run","description":"Create and start a new flow execution run.\n\nThis endpoint launches the execution of a flow with the provided inputs.\nThe execution runs asynchronously, allowing you to monitor progress and retrieve\nresults when complete.\n\nThe run executes the flow's **last saved version**. The flow builder autosaves\nyour edits as a private draft, and drafts never run here — save the flow to put\nyour latest changes behind the API.\n\n**Idempotency with `external_id`:** Optionally pass an `external_id` (e.g. your\nown order or job id). It is **unique per organization**: the first request with\na given key starts the run; any later write reusing that key — including a\ndropped-response retry — is rejected with **`409 conflict`** instead of starting\n(and charging) a duplicate. To fetch the run a key already created, use\n`GET /runs?external_id=...`. The id is echoed on every run response.\n\n- Scope: per organization, across **all** runs (flow and app share the key\n  space) and **all** statuses — a key, once used, stays used.\n- On `409`, do **not** keep retrying the create; `GET /runs?external_id=` to\n  retrieve the existing run (or `GET /app-runs?external_id=` if an app run\n  holds the key). To start a genuinely new run, use a new `external_id`.\n\n**How to Build Inputs:**\n\n1. **First, get flow details**: Call `GET /flows/{flow_id}` to retrieve the flow configuration\n2. **Examine the `inputs` array**: Each object defines what input the flow expects:\n   - `id`: Use this as the `id` in your input object\n   - `type`: Determines the input format (see below)\n   - `description`: Explains what this input does\n   - `required`: Whether the run is rejected without it. An omitted optional\n     input runs with the value saved in the flow.\n\n3. **Format inputs based on type** — `type` is always one of the five below:\n\n**Text Inputs** (`text_input` type) — a string, or a list of strings:\n```json\n{\n    \"id\": \"text_input_node_id\",\n    \"value\": \"Your text content here\"\n}\n```\n\n**Asset Inputs** (`image_input`, `video_input`, `audio_input`, `file_input` types):\n```json\n{\n    \"id\": \"image_input_node_id\",\n    \"value\": {\n        \"asset_ids\": [\"uuid1\", \"uuid2\"]\n    }\n}\n```\nNote: Upload assets first via `POST /assets/upload` to get the UUIDs. A bare\nlist of asset UUIDs is accepted as `value` too.\n\nNothing else in a flow can be set per run: brand (Brain) content and fonts\nare part of the saved flow, never listed in `inputs`.\n\n**Complete Example Workflow:**\n\n1. Get flow configuration:\n```bash\nGET /flows/550e8400-e29b-41d4-a716-446655440000\n# Response shows inputs: [\n#   {\"id\": \"uuid-1\", \"type\": \"text_input\", \"description\": \"Product description\"},\n#   {\"id\": \"uuid-2\", \"type\": \"image_input\", \"description\": \"Company logo\"}\n# ]\n```\n\n2. Upload assets if needed:\n```bash\nPOST /assets/upload\n# Response: {\"id\": \"asset-uuid-123\", ...}\n```\n\n3. Create run with matching inputs:\n```json\n{\n    \"flow_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"inputs\": [\n        {\n            \"id\": \"uuid-1\",\n            \"value\": \"Create a marketing banner for a tech startup\"\n        },\n        {\n            \"id\": \"uuid-2\",\n            \"value\": {\n                \"asset_ids\": [\"asset-uuid-123\"]\n            }\n        }\n    ]\n}\n```\n\n**Response:**\n- `201` with the Run object: `status` is `in_progress`, and `inputs` echoes\n  the request\n- Use `id` field to monitor progress via `GET /runs/{run_id}`\n- Credits are checked once execution starts: a run the organization cannot\n  afford ends `failed` with `failure_reason` `insufficient_credits`, not as an\n  error on this call\n\n**Running an app instead?** Apps have their own surface — use `POST /app-runs`\nwith an `app_id`. App runs pause on human review too, and are resolved via\n`POST /app-runs/{run_id}/reviews/{review_id}`. See the Apps and App Runs\nsections.\n\n**Error Codes:**\n- `400`: An input `id` the flow doesn't have, a missing required input, an\n  asset input without `asset_ids`, a flow with configuration errors, or a\n  flow that has never been saved and so has no version to run\n- `401`: Missing or invalid API key / Bearer token\n- `403`: `X-Organization-Id` names an organization you can't act in\n- `404`: Flow not found or not accessible\n- `409`: `external_id` is already used by a run in this organization\n- `422`: Malformed body (e.g. `flow_id` not a UUID, `external_id` over 255\n  characters), or input values the flow's nodes would reject before running\n- `429`: Rate limit exceeded — retry after the `Retry-After` header","operationId":"v1_create_run_runs__post","parameters":[{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}}}
````

## Get Run

> 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\`\
> &#x20;  and resolve each via \`POST /runs/{run\_id}/reviews/{review\_id}\` to\
> &#x20;  resume execution. A review left undecided for a week cancels the run\
> &#x20;  (\`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\
> &#x20; 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\
> &#x20; paused on a review); null once the run has ended\
> \- \`awaiting\_human\_review\`: \`true\` when the run is paused on a human\
> &#x20; 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\
> &#x20; via \`GET /app-runs/{run\_id}\`\
> \- \`422\`: \`run\_id\` is not a UUID

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel flow executions."}],"servers":[{"url":"/api/public"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Cognito JWT Bearer token"}},"schemas":{"Run":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"flow_id":{"type":"string","format":"uuid","title":"Flow Id","description":"ID of the flow being executed"},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id","description":"Client-supplied reference id provided at creation, if any"},"status":{"$ref":"#/components/schemas/FlowRunStatus","description":"Current execution state: `in_progress` until the run ends, then `completed`, `failed`, or `canceled`. Stays `in_progress` while paused on a human review."},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"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_node":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Node","description":"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_review":{"type":"boolean","title":"Awaiting Human Review","description":"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},"pending_reviews":{"items":{"$ref":"#/components/schemas/PendingReview"},"type":"array","title":"Pending Reviews","description":"Human review steps currently waiting for a decision. Empty unless `awaiting_human_review` is true."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the run was created"},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"When execution started"},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"When the run ended (completed, failed, or canceled). Null while in_progress."},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs for this run. The create response echoes the request as sent; later reads return the stored values (text as a list of strings, assets as {\"asset_ids\": [...]})."},"results":{"items":{"$ref":"#/components/schemas/RunResult"},"type":"array","title":"Results","description":"One entry per executed node that produced output — intermediate nodes included, not only the flow's `outputs`; match by `id`. Entries appear as nodes finish, so an in-progress or failed run can carry partial results. After a review `retry`, each node reports its latest output."},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Credits consumed so far, summed over the run's nodes. Grows while the run is in progress; null before any node has started."},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message when the run failed or was canceled. Null otherwise."},"failure_reason":{"anyOf":[{"$ref":"#/components/schemas/FailureReason"},{"type":"null"}],"description":"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."},"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"Deprecated alias for `flow_id`, removed 31 December 2026.","deprecated":true,"readOnly":true}},"type":"object","required":["id","flow_id","status","created_at","agent_id"],"title":"Run","description":"Complete representation of a flow execution run.\n\n`status` starts at `in_progress` and ends at `completed`, `failed` or\n`canceled`. A run paused on a human review stays `in_progress`, with\n`awaiting_human_review` true."},"FlowRunStatus":{"type":"string","enum":["in_progress","completed","failed","canceled"],"title":"FlowRunStatus","description":"Execution status of a workflow run."},"PendingReview":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Identifier of the pending review. Use this as `review_id` when calling POST /runs/{run_id}/reviews/{review_id} — or POST /app-runs/{run_id}/reviews/{review_id} for an app run — to resume execution. A `retry` keeps the same id: the review stays listed while the upstream output regenerates."},"node_id":{"type":"string","title":"Node Id","description":"ID of the human review node inside the flow definition"},"reviewed_node_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reviewed Node Type","description":"Type of the upstream node whose output is being reviewed (e.g. image_generation, llm). Null when that node has no execution record — input nodes (text/image/video/audio/file inputs) never do."},"reviewed_output_type":{"anyOf":[{"$ref":"#/components/schemas/DataType"},{"type":"null"}],"description":"Kind of output under review (text, images, videos, audio, data). Null when `reviewed_node_type` is null or has no public output mapping."},"proposed_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"string"},{"type":"null"}],"title":"Proposed Output","description":"Output of the reviewed upstream node (the first one, when the review covers several), in that node's own shape — e.g. {\"asset_ids\": [...]} for media. Submit it back (optionally edited) as `output` when approving. To discard items, submit only the ones you want to keep — omitted items are dropped. At least one item must be kept. Null when there is nothing to show: the review covers only input nodes, or the upstream node is still regenerating after a `retry`."},"can_edit_outputs":{"type":"boolean","title":"Can Edit Outputs","description":"Always true: every review step lets reviewers edit the proposed output.","default":true},"can_generate_more":{"type":"boolean","title":"Can Generate More","description":"Whether the review step offers regenerating the upstream output (decision `retry`). Always false when the review only covers input nodes. Informational: the API does not enforce it.","default":false},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the review was opened"}},"type":"object","required":["id","node_id","created_at"],"title":"PendingReview","description":"A human review step that is currently waiting for a decision.\n\nShared by runs and app runs: both pause on human review nodes the same way."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Kind of content an output, run result or review carries. In run results,\n`text` values are text, `images` / `videos` / `audio` values are asset IDs\nto download, and `data` values are structured JSON."},"RunInput":{"properties":{"id":{"type":"string","title":"Id","description":"ID of the input this value fills, as listed in the `inputs` of the flow or app"},"value":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"title":"Value","description":"Input value. Text inputs take a string, or a list of strings. Image, video, audio and file inputs take {\"asset_ids\": [\"uuid\", ...]} (a bare list of asset IDs is also accepted). Upload files first via POST /assets/upload. When read back from a stored run, text values come back as a list of strings and asset values as {\"asset_ids\": [...]}."}},"type":"object","required":["id","value"],"title":"RunInput","description":"Represents an input provided to a run.\n\nShared by runs and app runs: both pipelines accept the same wire shape."},"RunResult":{"properties":{"id":{"type":"string","title":"Id","description":"ID of the node that produced this result. Match it against the `id` of an entry in the flow's or app's `outputs`."},"type":{"$ref":"#/components/schemas/DataType","description":"Kind of result: `text`, `images`, `videos`, `audio`, or `data` (structured output, and any node type without a more specific mapping)"},"value":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Result content. `text`: a string, or a list of strings when the node produced several. `images` / `videos` / `audio`: a list of asset IDs — resolve each via GET /assets/{id}. `data`: the node's raw output object."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Generic label for the result kind (e.g. \"Generated images\")"}},"type":"object","required":["id","type"],"title":"RunResult","description":"Represents a result produced by a run.\n\nShared by runs and app runs: both pipelines emit the same wire shape."},"FailureReason":{"type":"string","enum":["timeout","content_policy","insufficient_credits","invalid_input","provider_error","provider_auth_required","canceled","unknown"],"title":"FailureReason","description":"Stable category for why a run failed: `timeout` (a step ran out of time),\n`content_policy` (blocked by content moderation), `insufficient_credits`\n(credit or quota exhausted), `invalid_input` (an input, or an uploaded file,\ncould not be used), `provider_error` (an upstream AI provider failed),\n`provider_auth_required` (a connected provider account is missing or expired\nand must be reconnected), `canceled` (the run was canceled), `unknown` (any\ncause without a category of its own)."},"ApiErrorResponse":{"description":"Standard error response envelope. All API errors follow this format.","properties":{"error":{"$ref":"#/components/schemas/ApiErrorDetail","description":"Error details"}},"required":["error"],"title":"ApiErrorResponse","type":"object"},"ApiErrorDetail":{"description":"Structured details for an API error.","properties":{"code":{"$ref":"#/components/schemas/ApiErrorCode","description":"Machine-readable error code; branch on this, not on `message`"},"message":{"description":"Human-readable error description","title":"Message","type":"string"},"status":{"description":"HTTP status code of this response","title":"Status","type":"integer"},"details":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}]},"description":"Additional context. Always holds `request_id` (the response's `X-Request-Id`); `validation_error` from request validation adds `errors`, a list of `location: message` strings, and `rate_limit_exceeded` adds `retry_after`, the seconds to wait.","title":"Details","type":"object"}},"required":["code","message","status","details"],"title":"ApiErrorDetail","type":"object"},"ApiErrorCode":{"description":"Machine-readable error code, with its usual HTTP status: `invalid_input`\n400, `authentication_required` 401, `forbidden` 403, `not_found` 404,\n`conflict` 409, `validation_error` 422, `rate_limit_exceeded` 429,\n`internal_error` 500, `run_failed` 502, `service_unavailable` 503, `timeout`\n504. A 4xx status without a code of its own is sent as `invalid_input`.\n\n`plan_required`, `credit_usage_exceeded`, `user_quota_exceeded`,\n`spend_limit_exceeded`, `brain_flow_impact`, `stale_definition`,\n`flow_not_shared` and `asset_not_ready` have no status of their own and are\nsent only in the `X-Pletor-Error-Code` response header, never as `code`.","enum":["invalid_input","authentication_required","forbidden","not_found","conflict","validation_error","rate_limit_exceeded","internal_error","run_failed","service_unavailable","timeout","plan_required","credit_usage_exceeded","user_quota_exceeded","spend_limit_exceeded","brain_flow_impact","stale_definition","flow_not_shared","asset_not_ready"],"title":"ApiErrorCode","type":"string"}}},"paths":{"/v1/runs/{run_id}":{"get":{"tags":["runs"],"summary":"Get Run","description":"Get detailed information about a specific flow execution run.\n\nThis endpoint retrieves comprehensive information about an execution run,\nincluding real-time status, progress, inputs, and results when available.\n\n**Monitoring Workflow:**\n1. Create run via `POST /runs`\n2. Poll this endpoint to monitor progress\n3. If `awaiting_human_review` becomes `true`, inspect `pending_reviews`\n   and resolve each via `POST /runs/{run_id}/reviews/{review_id}` to\n   resume execution. A review left undecided for a week cancels the run\n   (`failure_reason: timeout`).\n4. Stop polling when status becomes \"completed\", \"failed\", or \"canceled\"\n5. Extract results from the `results` array when status is \"completed\"\n\n**Status Lifecycle:**\n- `in_progress`: Executing, or paused on a human review\n- `completed`: Every node finished\n- `failed`: A node failed, or credits ran out. Nodes that finished first\n  keep their `results`, so they can be partial\n- `canceled`: Stopped via `DELETE /runs/{run_id}`\n\n**Progress Tracking:**\n- `status`: Current execution state\n- `progress`: Rough completion indicator (0.0 to 1.0)\n- `current_node`: Type of a node currently executing (`human_review` while\n  paused on a review); null once the run has ended\n- `awaiting_human_review`: `true` when the run is paused on a human\n  review node; `status` stays `in_progress` in this case\n- `pending_reviews`: List of review steps awaiting a decision\n- `created_at` / `started_at`: When the run was created / started executing\n- `completed_at`: When the run ended (if applicable)\n\n**How to Retrieve Results:**\n\nWhen the run status becomes \"completed\", the `results` array contains the flow outputs.\nCall `GET /flows/{flow_id}` and examine the `outputs` array to understand what\nresults to expect, then match results to outputs by `id`. `results` also\ncarries intermediate nodes' outputs — ignore the ids you don't need.\n\n**Text Results** (`type` `text`): `value` is a string, or a list of strings.\n\n**Asset Results** (`images`, `videos`, `audio`): `value` is an array of asset UUIDs.\nResolve each via `GET /assets/{id}` and fetch the `url` field.\n\n**Data Results** (`data`): `value` is the node's raw output object.\n\n**Cost Information:**\n- `cost`: Credits consumed so far; final once the run has ended\n\n**Error Handling:**\n- `error`: Error message if the run failed or was canceled\n- `failure_reason`: Categorized cause, set when the run failed or was canceled\n\n**Error Codes:**\n- `401` / `403` / `429`: Authentication, organization access, or rate limit\n- `404`: Run not found or not accessible — including app runs, which are read\n  via `GET /app-runs/{run_id}`\n- `422`: `run_id` is not a UUID","operationId":"v1_get_run_runs__run_id__get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of a flow run, from `POST /runs` or `GET /runs`. App runs are not found here; use `/app-runs/{run_id}`.","title":"Run Id"},"description":"ID of a flow run, from `POST /runs` or `GET /runs`. App runs are not found here; use `/app-runs/{run_id}`."},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}}}
```

## Cancel Run

> 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\
> &#x20; seconds later, with \`failure\_reason\` \`canceled\`\
> \- Nodes that already finished keep their \`results\`, and credits they\
> &#x20; 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\
> &#x20; longer \`in\_progress\` (completed, failed, or already canceled) — so a\
> &#x20; repeated cancel returns \`404\`\
> \- \`422\`: \`run\_id\` is not a UUID

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel flow executions."}],"servers":[{"url":"/api/public"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Cognito JWT Bearer token"}},"schemas":{"ApiErrorResponse":{"description":"Standard error response envelope. All API errors follow this format.","properties":{"error":{"$ref":"#/components/schemas/ApiErrorDetail","description":"Error details"}},"required":["error"],"title":"ApiErrorResponse","type":"object"},"ApiErrorDetail":{"description":"Structured details for an API error.","properties":{"code":{"$ref":"#/components/schemas/ApiErrorCode","description":"Machine-readable error code; branch on this, not on `message`"},"message":{"description":"Human-readable error description","title":"Message","type":"string"},"status":{"description":"HTTP status code of this response","title":"Status","type":"integer"},"details":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}]},"description":"Additional context. Always holds `request_id` (the response's `X-Request-Id`); `validation_error` from request validation adds `errors`, a list of `location: message` strings, and `rate_limit_exceeded` adds `retry_after`, the seconds to wait.","title":"Details","type":"object"}},"required":["code","message","status","details"],"title":"ApiErrorDetail","type":"object"},"ApiErrorCode":{"description":"Machine-readable error code, with its usual HTTP status: `invalid_input`\n400, `authentication_required` 401, `forbidden` 403, `not_found` 404,\n`conflict` 409, `validation_error` 422, `rate_limit_exceeded` 429,\n`internal_error` 500, `run_failed` 502, `service_unavailable` 503, `timeout`\n504. A 4xx status without a code of its own is sent as `invalid_input`.\n\n`plan_required`, `credit_usage_exceeded`, `user_quota_exceeded`,\n`spend_limit_exceeded`, `brain_flow_impact`, `stale_definition`,\n`flow_not_shared` and `asset_not_ready` have no status of their own and are\nsent only in the `X-Pletor-Error-Code` response header, never as `code`.","enum":["invalid_input","authentication_required","forbidden","not_found","conflict","validation_error","rate_limit_exceeded","internal_error","run_failed","service_unavailable","timeout","plan_required","credit_usage_exceeded","user_quota_exceeded","spend_limit_exceeded","brain_flow_impact","stale_definition","flow_not_shared","asset_not_ready"],"title":"ApiErrorCode","type":"string"}}},"paths":{"/v1/runs/{run_id}":{"delete":{"tags":["runs"],"summary":"Cancel Run","description":"Cancel an ongoing flow execution run.\n\nThis endpoint stops a run whose `status` is `in_progress` — including one\npaused on a human review. Once cancelled, the execution cannot be resumed.\n\n**Behavior:**\n- Only `in_progress` runs can be cancelled\n- `204` means cancellation was requested; `status` becomes `canceled` a few\n  seconds later, with `failure_reason` `canceled`\n- Nodes that already finished keep their `results`, and credits they\n  consumed stay in `cost`\n- Pending reviews can no longer be submitted (`409`)\n- App runs are cancelled via `DELETE /app-runs/{run_id}`\n\n**Error Codes:**\n- `401` / `403` / `429`: Authentication, organization access, or rate limit\n- `404`: Run not found or not accessible, an app run, or a run that is no\n  longer `in_progress` (completed, failed, or already canceled) — so a\n  repeated cancel returns `404`\n- `422`: `run_id` is not a UUID","operationId":"v1_cancel_run_runs__run_id__delete","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of a flow run, from `POST /runs` or `GET /runs`. App runs are not found here; use `/app-runs/{run_id}`.","title":"Run Id"},"description":"ID of a flow run, from `POST /runs` or `GET /runs`. App runs are not found here; use `/app-runs/{run_id}`."},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}}}
```

## Submit Review

> 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\
> &#x20;  \`review\_id\` in this endpoint's path.\
> 3\. The \`proposed\_output\` field of each review is what the upstream node\
> &#x20;  generated. Submit it back as \`output\` (optionally edited) to approve.\
> \
> \*\*Decisions\*\*\
> \
> \- \`approve\`: continue execution. The \`output\` body field is required and\
> &#x20; must match the shape of \`proposed\_output\`:\
> &#x20; \- Image / video / audio reviews: \`{"asset\_ids": \["..."]}\`.\
> &#x20; \- Text reviews: \`{"prompts": \["..."]}\` (the reviewed node's own text key,\
> &#x20;   as seen in \`proposed\_output\`, is accepted too).\
> &#x20; To discard items, approve with only the ones you want to keep — omitted\
> &#x20; items are dropped. At least one item must be kept (an empty \`output\` is\
> &#x20; rejected with \`400\`).\
> \- \`retry\`: re-run the upstream node(s) to produce a new candidate output.\
> &#x20; \`output\` is ignored. The review keeps its \`id\` and stays in\
> &#x20; \`pending\_reviews\`; its \`proposed\_output\` is null while the upstream\
> &#x20; node regenerates, then shows the new candidate — decide again once it\
> &#x20; does. \`can\_generate\_more\` tells you whether the flow offers this; the\
> &#x20; 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:\
> \`\`\`json\
> {\
> &#x20;   "decision": "approve",\
> &#x20;   "output": {\
> &#x20;       "asset\_ids": \[\
> &#x20;           "asset-uuid-001",\
> &#x20;           "asset-uuid-002"\
> &#x20;       ]\
> &#x20;   }\
> }\
> \`\`\`\
> \
> Discard some of the proposed assets by approving with only the kept subset:\
> \`\`\`json\
> {"decision": "approve", "output": {"asset\_ids": \["asset-uuid-001"]}}\
> \`\`\`\
> \
> Retry to regenerate the upstream output:\
> \`\`\`json\
> {"decision": "retry"}\
> \`\`\`\
> \
> \*\*Error Codes:\*\*\
> \- \`400\`: Missing \`output\`, an empty \`output\` (nothing kept), or an \`output\`\
> &#x20; 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\
> &#x20; with that ID on this run.\
> \- \`409\`: The review is no longer waiting (already submitted, or the run\
> &#x20; finished/failed/was canceled). Checked before the review ID, so any\
> &#x20; \`review\_id\` on an ended run returns \`409\`.\
> \- \`422\`: Malformed body (e.g. a \`decision\` other than \`approve\`/\`retry\`),\
> &#x20; or a path ID that is not a UUID.

````json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"2.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel flow executions."}],"servers":[{"url":"/api/public"}],"security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"API key for authentication"},"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Cognito JWT Bearer token"}},"schemas":{"SubmitReviewRequest":{"properties":{"decision":{"$ref":"#/components/schemas/ReviewDecision","description":"`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":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"string"},{"type":"null"}],"title":"Output","description":"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."}},"type":"object","required":["decision"],"title":"SubmitReviewRequest","description":"Request to resolve a pending human review."},"ReviewDecision":{"type":"string","enum":["approve","retry"],"title":"ReviewDecision","description":"Possible decisions when responding to a pending human review.\n\n`approve` resumes the run with the submitted output; `retry` re-runs the\nreviewed upstream node(s) and waits for a new decision on the same review."},"ApiErrorResponse":{"description":"Standard error response envelope. All API errors follow this format.","properties":{"error":{"$ref":"#/components/schemas/ApiErrorDetail","description":"Error details"}},"required":["error"],"title":"ApiErrorResponse","type":"object"},"ApiErrorDetail":{"description":"Structured details for an API error.","properties":{"code":{"$ref":"#/components/schemas/ApiErrorCode","description":"Machine-readable error code; branch on this, not on `message`"},"message":{"description":"Human-readable error description","title":"Message","type":"string"},"status":{"description":"HTTP status code of this response","title":"Status","type":"integer"},"details":{"additionalProperties":{"anyOf":[{"type":"string"},{"type":"integer"},{"type":"number"},{"type":"boolean"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":{"type":"string"},"type":"object"},{"type":"null"}]},"description":"Additional context. Always holds `request_id` (the response's `X-Request-Id`); `validation_error` from request validation adds `errors`, a list of `location: message` strings, and `rate_limit_exceeded` adds `retry_after`, the seconds to wait.","title":"Details","type":"object"}},"required":["code","message","status","details"],"title":"ApiErrorDetail","type":"object"},"ApiErrorCode":{"description":"Machine-readable error code, with its usual HTTP status: `invalid_input`\n400, `authentication_required` 401, `forbidden` 403, `not_found` 404,\n`conflict` 409, `validation_error` 422, `rate_limit_exceeded` 429,\n`internal_error` 500, `run_failed` 502, `service_unavailable` 503, `timeout`\n504. A 4xx status without a code of its own is sent as `invalid_input`.\n\n`plan_required`, `credit_usage_exceeded`, `user_quota_exceeded`,\n`spend_limit_exceeded`, `brain_flow_impact`, `stale_definition`,\n`flow_not_shared` and `asset_not_ready` have no status of their own and are\nsent only in the `X-Pletor-Error-Code` response header, never as `code`.","enum":["invalid_input","authentication_required","forbidden","not_found","conflict","validation_error","rate_limit_exceeded","internal_error","run_failed","service_unavailable","timeout","plan_required","credit_usage_exceeded","user_quota_exceeded","spend_limit_exceeded","brain_flow_impact","stale_definition","flow_not_shared","asset_not_ready"],"title":"ApiErrorCode","type":"string"}}},"paths":{"/v1/runs/{run_id}/reviews/{review_id}":{"post":{"tags":["runs"],"summary":"Submit Review","description":"Resolve a pending human review and resume an execution.\n\nWhen a flow includes a human review step, the run pauses on that node\nand `awaiting_human_review` becomes `true` on `GET /runs/{run_id}` (and\n`has_human_review` is `true` on the flow). Each waiting step is listed in\nthe run's `pending_reviews` array, and `status` stays `in_progress`.\nSubmit a decision here to resume. A review left undecided for one week\nfails the run.\n\nThis endpoint serves flow runs only. App runs pause the same way; resolve\ntheirs via `POST /app-runs/{run_id}/reviews/{review_id}`.\n\n**Discovering pending reviews**\n\n1. Poll `GET /runs/{run_id}` until `awaiting_human_review` is `true`.\n2. Inspect the `pending_reviews` array. Use a review's `id` as\n   `review_id` in this endpoint's path.\n3. The `proposed_output` field of each review is what the upstream node\n   generated. Submit it back as `output` (optionally edited) to approve.\n\n**Decisions**\n\n- `approve`: continue execution. The `output` body field is required and\n  must match the shape of `proposed_output`:\n  - Image / video / audio reviews: `{\"asset_ids\": [\"...\"]}`.\n  - Text reviews: `{\"prompts\": [\"...\"]}` (the reviewed node's own text key,\n    as seen in `proposed_output`, is accepted too).\n  To discard items, approve with only the ones you want to keep — omitted\n  items are dropped. At least one item must be kept (an empty `output` is\n  rejected with `400`).\n- `retry`: re-run the upstream node(s) to produce a new candidate output.\n  `output` is ignored. The review keeps its `id` and stays in\n  `pending_reviews`; its `proposed_output` is null while the upstream\n  node regenerates, then shows the new candidate — decide again once it\n  does. `can_generate_more` tells you whether the flow offers this; the\n  API accepts `retry` regardless.\n\nA `204` means the decision was delivered; poll `GET /runs/{run_id}` to\nfollow the run from there.\n\n**Examples**\n\nApprove an image review using the proposed assets:\n```json\n{\n    \"decision\": \"approve\",\n    \"output\": {\n        \"asset_ids\": [\n            \"asset-uuid-001\",\n            \"asset-uuid-002\"\n        ]\n    }\n}\n```\n\nDiscard some of the proposed assets by approving with only the kept subset:\n```json\n{\"decision\": \"approve\", \"output\": {\"asset_ids\": [\"asset-uuid-001\"]}}\n```\n\nRetry to regenerate the upstream output:\n```json\n{\"decision\": \"retry\"}\n```\n\n**Error Codes:**\n- `400`: Missing `output`, an empty `output` (nothing kept), or an `output`\n  whose shape doesn't match the review, when decision is `approve`.\n- `401` / `403` / `429`: Authentication, organization access, or rate limit.\n- `404`: Run not found (app runs included — see above), or no human review\n  with that ID on this run.\n- `409`: The review is no longer waiting (already submitted, or the run\n  finished/failed/was canceled). Checked before the review ID, so any\n  `review_id` on an ended run returns `409`.\n- `422`: Malformed body (e.g. a `decision` other than `approve`/`retry`),\n  or a path ID that is not a UUID.","operationId":"v1_submit_review_runs__run_id__reviews__review_id__post","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"ID of a flow run, from `POST /runs` or `GET /runs`. App runs are not found here; use `/app-runs/{run_id}`.","title":"Run Id"},"description":"ID of a flow run, from `POST /runs` or `GET /runs`. App runs are not found here; use `/app-runs/{run_id}`."},{"name":"review_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","description":"`id` of an entry in the run's `pending_reviews`","title":"Review Id"},"description":"`id` of an entry in the run's `pending_reviews`"},{"name":"X-Organization-Id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Active organization ID for multi-org support","title":"X-Organization-Id"},"description":"Active organization ID for multi-org support"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitReviewRequest"}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation error (`validation_error`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}}}
````
