> 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/runs.md).

# Runs

Create, monitor, and cancel agent executions.

## List Runs

> List agent execution runs with filtering options.\
> \
> This endpoint returns a paginated list of agent execution runs 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)\
> \- \`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.\
> \
> \*\*Pagination Parameters:\*\*\
> \- \`limit\`: Maximum number of items to return (default: 20, max: 100)\
> \- \`cursor\`: Cursor for pagination (optional)\
> \
> \*\*Response:\*\*\
> \- \`data\`: List of run summaries with basic information\
> \- \`has\_more\`: Indicates if there are more results available\
> \- \`next\_cursor\`: Cursor for the next page of results\
> \
> \*\*Use Case:\*\* Monitor multiple executions and their status overview.

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel agent executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"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"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"ID of the agent 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"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Completion progress from 0.0 to 1.0","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 execution finished"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Total credits consumed by this run"}},"type":"object","required":["id","agent_id","status","created_at"],"title":"RunSummary","description":"Lightweight run summary for list views."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/runs/":{"get":{"tags":["runs"],"summary":"List Runs","description":"List agent execution runs with filtering options.\n\nThis endpoint returns a paginated list of agent execution runs with their\ncurrent status and basic metadata. App runs are listed separately via\n`GET /app-runs`.\n\n**Filtering Options:**\n- `status`: Filter by execution status (in_progress, completed, failed, canceled)\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.\n\n**Pagination Parameters:**\n- `limit`: Maximum number of items to return (default: 20, max: 100)\n- `cursor`: Cursor for pagination (optional)\n\n**Response:**\n- `data`: List of run summaries with basic information\n- `has_more`: Indicates if there are more results available\n- `next_cursor`: Cursor for the next page of results\n\n**Use Case:** Monitor multiple executions and their status overview.","operationId":"list_runs_runs__get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/FlowRunStatus"},{"type":"null"}],"title":"Status"}},{"name":"external_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"}},{"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Create Run

> Create and start a new agent execution run.\
> \
> This endpoint launches the execution of an AI agent with the provided inputs.\
> The execution runs asynchronously, allowing you to monitor progress and retrieve\
> results when complete.\
> \
> \*\*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 (agent 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. To start a genuinely new run, use a new \`external\_id\`.\
> \
> \*\*How to Build Inputs:\*\*\
> \
> 1\. \*\*First, get agent details\*\*: Call \`GET /agents/{agent\_id}\` to retrieve the agent configuration\
> 2\. \*\*Examine the \`inputs\` array\*\*: Each object defines what input the agent expects:\
>    \- \`id\`: Use this as the \`id\` in your input object\
>    \- \`type\`: Determines the input format (see below)\
>    \- \`description\`: Explains what this input does\
> \
> 3\. \*\*Format inputs based on type\*\*:\
> \
> \*\*Text Inputs\*\* (\`text\_input\` type):\
> \`\`\`json\
> {\
>     "id": "text\_input\_node\_id",\
>     "value": "Your text content here"\
> }\
> \`\`\`\
> \
> \*\*Asset Inputs\*\* (\`image\_input\`, \`video\_input\`, \`file\_input\` types):\
> \`\`\`json\
> {\
>     "id": "image\_input\_node\_id",\
>     "value": {\
>         "asset\_ids": \["uuid1", "uuid2"]\
>     }\
> }\
> \`\`\`\
> Note: Upload assets first via \`POST /assets/upload\` to get the UUIDs\
> \
> \*\*Complete Example Workflow:\*\*\
> \
> 1\. Get agent configuration:\
> \`\`\`bash\
> GET /agents/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\
> {\
>     "agent\_id": "550e8400-e29b-41d4-a716-446655440000",\
>     "inputs": \[\
>         {\
>             "id": "uuid-1",\
>             "value": "Create a marketing banner for a tech startup"\
>         },\
>         {\
>             "id": "uuid-2",\
>             "value": {\
>                 "asset\_ids": \["asset-uuid-123"]\
>             }\
>         }\
>     ]\
> }\
> \`\`\`\
> \
> \*\*Response:\*\*\
> \- Run object with execution details and initial status\
> \- Use \`id\` field to monitor progress via \`GET /runs/{run\_id}\`\
> \
> \*\*Running an app instead?\*\* Apps have their own surface — use \`POST /app-runs\`\
> with an \`app\_id\`. See the Apps and App Runs sections.\
> \
> \*\*Error Codes:\*\*\
> \- \`400\`: Invalid input format or missing required inputs\
> \- \`404\`: Agent not found or not accessible

````json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel agent executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"RunCreateRequest":{"properties":{"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"ID of the agent to execute"},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs for the agent. Get required inputs from GET /agents/{id}"},"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). Unique per organization: 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= to fetch it. Use a new id per run."}},"type":"object","required":["agent_id"],"title":"RunCreateRequest","description":"Request to create and start a new agent execution run."},"RunInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID that this input targets"},"value":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"title":"Value","description":"Input value: plain text string for text inputs, or {\"asset_ids\": [\"uuid\"]} for asset inputs"}},"type":"object","required":["id","value"],"title":"RunInput","description":"Represents an input provided to a run.\n\nShared by agent runs and app runs: both pipelines accept the same wire shape."},"Run":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"ID of the agent 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, completed, failed, or canceled"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Completion progress from 0.0 to 1.0","default":0},"current_node":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Node","description":"Type of the node currently executing (e.g. image_generation, llm). Only present while 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 execution finished"},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs provided for this run"},"results":{"items":{"$ref":"#/components/schemas/RunResult"},"type":"array","title":"Results","description":"Output results, populated when status is completed"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Total credits consumed by this run"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if the run failed"},"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."}},"type":"object","required":["id","agent_id","status","created_at"],"title":"Run","description":"Complete representation of an agent execution run."},"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} to resume execution."},"node_id":{"type":"string","title":"Node Id","description":"ID of the human review node inside the agent 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). May be null for legacy reviews."},"reviewed_output_type":{"anyOf":[{"$ref":"#/components/schemas/DataType"},{"type":"null"}],"description":"Business-friendly type of the output under review (text, images, videos, audio, files, data)."},"proposed_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"string"},{"type":"null"}],"title":"Proposed Output","description":"Output produced by the upstream node(s) that is being reviewed. Submit this 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."},"can_edit_outputs":{"type":"boolean","title":"Can Edit Outputs","description":"Whether the agent definition allows editing the proposed output before approval.","default":false},"can_generate_more":{"type":"boolean","title":"Can Generate More","description":"Whether the agent definition allows regenerating the upstream output (decision=retry).","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."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Types of data that agents can accept as input or produce as output."},"RunResult":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID that produced this result"},"type":{"$ref":"#/components/schemas/DataType","description":"Type of the result data"},"value":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Result content: text string, list of asset UUIDs, or structured data"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description of the result"}},"type":"object","required":["id","type"],"title":"RunResult","description":"Represents a result produced by a run.\n\nShared by agent 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, client-facing categories for why a run failed. A curated public\nview over the internal `NodeFailureReason`; internal-only causes collapse to\n`unknown` so the public contract stays stable as internals change."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/runs/":{"post":{"tags":["runs"],"summary":"Create Run","description":"Create and start a new agent execution run.\n\nThis endpoint launches the execution of an AI agent with the provided inputs.\nThe execution runs asynchronously, allowing you to monitor progress and retrieve\nresults when complete.\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 (agent 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. To start a genuinely new run, use a new `external_id`.\n\n**How to Build Inputs:**\n\n1. **First, get agent details**: Call `GET /agents/{agent_id}` to retrieve the agent configuration\n2. **Examine the `inputs` array**: Each object defines what input the agent 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\n3. **Format inputs based on type**:\n\n**Text Inputs** (`text_input` type):\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`, `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\n\n**Complete Example Workflow:**\n\n1. Get agent configuration:\n```bash\nGET /agents/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    \"agent_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- Run object with execution details and initial status\n- Use `id` field to monitor progress via `GET /runs/{run_id}`\n\n**Running an app instead?** Apps have their own surface — use `POST /app-runs`\nwith an `app_id`. See the Apps and App Runs sections.\n\n**Error Codes:**\n- `400`: Invalid input format or missing required inputs\n- `404`: Agent not found or not accessible","operationId":"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````

## Get Run

> Get detailed information about a specific agent 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\
> 4\. Stop polling when status becomes "completed", "failed", or "canceled"\
> 5\. Extract results from the \`results\` array when status is "completed"\
> \
> \*\*Progress Tracking:\*\*\
> \- \`status\`: Current execution state\
> \- \`progress\`: Completion percentage (0.0 to 1.0)\
> \- \`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\`: When execution started\
> \- \`completed\_at\`: When execution finished (if applicable)\
> \
> \*\*How to Retrieve Results:\*\*\
> \
> When the run status becomes "completed", the \`results\` array contains the agent outputs.\
> Call \`GET /agents/{agent\_id}\` and examine the \`outputs\` array to understand what\
> results to expect, then match results to outputs by \`id\`:\
> \
> \*\*Text Results\*\*: Use \`value\` directly as string.\
> \
> \*\*Asset Results\*\* (images/videos/audio): \`value\` is an array of asset UUIDs.\
> Resolve each via \`GET /assets/{id}\` and fetch the \`url\` field.\
> \
> \*\*Cost Information:\*\*\
> \- \`cost\`: Total credits consumed by the execution\
> \
> \*\*Error Handling:\*\*\
> \- \`error\`: Error message if execution failed\
> \- \`failure\_reason\`: Categorized failure cause\
> \
> \*\*Error Codes:\*\*\
> \- \`404\`: Run not found or not accessible

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel agent executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"Run":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"Unique run identifier"},"agent_id":{"type":"string","format":"uuid","title":"Agent Id","description":"ID of the agent 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, completed, failed, or canceled"},"progress":{"type":"number","maximum":1,"minimum":0,"title":"Progress","description":"Completion progress from 0.0 to 1.0","default":0},"current_node":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Node","description":"Type of the node currently executing (e.g. image_generation, llm). Only present while 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 execution finished"},"inputs":{"items":{"$ref":"#/components/schemas/RunInput"},"type":"array","title":"Inputs","description":"Inputs provided for this run"},"results":{"items":{"$ref":"#/components/schemas/RunResult"},"type":"array","title":"Results","description":"Output results, populated when status is completed"},"cost":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cost","description":"Total credits consumed by this run"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if the run failed"},"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."}},"type":"object","required":["id","agent_id","status","created_at"],"title":"Run","description":"Complete representation of an agent execution run."},"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} to resume execution."},"node_id":{"type":"string","title":"Node Id","description":"ID of the human review node inside the agent 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). May be null for legacy reviews."},"reviewed_output_type":{"anyOf":[{"$ref":"#/components/schemas/DataType"},{"type":"null"}],"description":"Business-friendly type of the output under review (text, images, videos, audio, files, data)."},"proposed_output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"},{"type":"string"},{"type":"null"}],"title":"Proposed Output","description":"Output produced by the upstream node(s) that is being reviewed. Submit this 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."},"can_edit_outputs":{"type":"boolean","title":"Can Edit Outputs","description":"Whether the agent definition allows editing the proposed output before approval.","default":false},"can_generate_more":{"type":"boolean","title":"Can Generate More","description":"Whether the agent definition allows regenerating the upstream output (decision=retry).","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."},"DataType":{"type":"string","enum":["text","images","videos","files","audio","data"],"title":"DataType","description":"Types of data that agents can accept as input or produce as output."},"RunInput":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID that this input targets"},"value":{"anyOf":[{"type":"string"},{"additionalProperties":true,"type":"object"},{"items":{},"type":"array"}],"title":"Value","description":"Input value: plain text string for text inputs, or {\"asset_ids\": [\"uuid\"]} for asset inputs"}},"type":"object","required":["id","value"],"title":"RunInput","description":"Represents an input provided to a run.\n\nShared by agent runs and app runs: both pipelines accept the same wire shape."},"RunResult":{"properties":{"id":{"type":"string","title":"Id","description":"Node ID that produced this result"},"type":{"$ref":"#/components/schemas/DataType","description":"Type of the result data"},"value":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Value","description":"Result content: text string, list of asset UUIDs, or structured data"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Human-readable description of the result"}},"type":"object","required":["id","type"],"title":"RunResult","description":"Represents a result produced by a run.\n\nShared by agent 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, client-facing categories for why a run failed. A curated public\nview over the internal `NodeFailureReason`; internal-only causes collapse to\n`unknown` so the public contract stays stable as internals change."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/runs/{run_id}":{"get":{"tags":["runs"],"summary":"Get Run","description":"Get detailed information about a specific agent 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\n4. Stop polling when status becomes \"completed\", \"failed\", or \"canceled\"\n5. Extract results from the `results` array when status is \"completed\"\n\n**Progress Tracking:**\n- `status`: Current execution state\n- `progress`: Completion percentage (0.0 to 1.0)\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`: When execution started\n- `completed_at`: When execution finished (if applicable)\n\n**How to Retrieve Results:**\n\nWhen the run status becomes \"completed\", the `results` array contains the agent outputs.\nCall `GET /agents/{agent_id}` and examine the `outputs` array to understand what\nresults to expect, then match results to outputs by `id`:\n\n**Text Results**: Use `value` directly as string.\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**Cost Information:**\n- `cost`: Total credits consumed by the execution\n\n**Error Handling:**\n- `error`: Error message if execution failed\n- `failure_reason`: Categorized failure cause\n\n**Error Codes:**\n- `404`: Run not found or not accessible","operationId":"get_run_runs__run_id__get","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Cancel Run

> Cancel an ongoing agent execution run.\
> \
> This endpoint allows you to cancel an execution that is currently running\
> or pending. Once cancelled, the execution cannot be resumed.\
> \
> \*\*Behavior:\*\*\
> \- Only running or pending executions can be cancelled\
> \- Completed or failed executions cannot be cancelled\
> \- Cancellation may take a few seconds to take effect\
> \
> \*\*Error Codes:\*\*\
> \- \`404\`: Run not found or not accessible

```json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel agent executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/runs/{run_id}":{"delete":{"tags":["runs"],"summary":"Cancel Run","description":"Cancel an ongoing agent execution run.\n\nThis endpoint allows you to cancel an execution that is currently running\nor pending. Once cancelled, the execution cannot be resumed.\n\n**Behavior:**\n- Only running or pending executions can be cancelled\n- Completed or failed executions cannot be cancelled\n- Cancellation may take a few seconds to take effect\n\n**Error Codes:**\n- `404`: Run not found or not accessible","operationId":"cancel_run_runs__run_id__delete","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"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","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Submit Review

> Resolve a pending human review and resume an execution.\
> \
> When an agent includes a human review step, the run pauses on that node\
> and \`awaiting\_human\_review\` becomes \`true\` on \`GET /runs/{run\_id}\`. Each\
> waiting step is listed in the run's \`pending\_reviews\` array. Submit a\
> decision here to resume.\
> \
> \*\*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-prompt reviews: \`{"prompts": \["..."]}\`.\
>   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.\
>   The run goes back to "in progress"; poll again to retrieve the new\
>   \`pending\_reviews\` entry once it's ready. \`output\` is ignored.\
> \
> \*\*Examples\*\*\
> \
> Approve an image review using the proposed assets:\
> \`\`\`json\
> {\
>     "decision": "approve",\
>     "output": {\
>         "asset\_ids": \[\
>             "asset-uuid-001",\
>             "asset-uuid-002"\
>         ]\
>     }\
> }\
> \`\`\`\
> \
> 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\`, or an empty \`output\` (nothing kept), when\
>   decision is \`approve\`.\
> \- \`404\`: Run not found, or no pending review with that ID on this run.\
> \- \`409\`: The review is no longer waiting (already submitted, or the run\
>   finished/failed/was canceled).

````json
{"openapi":"3.1.0","info":{"title":"Pletor - Public API","version":"1.0.0"},"tags":[{"name":"runs","description":"Create, monitor, and cancel agent executions."}],"servers":[{"url":"https://api.pletor.ai/api/public/v1","description":"Production"}],"security":[{"APIKeyHeader":[]}],"components":{"securitySchemes":{},"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."},"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`. Ignored when decision is `retry`. Must match the shape of `proposed_output` ({\"asset_ids\": [...]} for image/video/audio reviews, or {\"prompts\": [...]} for text-prompt reviews). 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."}},"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."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/runs/{run_id}/reviews/{review_id}":{"post":{"tags":["runs"],"summary":"Submit Review","description":"Resolve a pending human review and resume an execution.\n\nWhen an agent includes a human review step, the run pauses on that node\nand `awaiting_human_review` becomes `true` on `GET /runs/{run_id}`. Each\nwaiting step is listed in the run's `pending_reviews` array. Submit a\ndecision here to resume.\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-prompt reviews: `{\"prompts\": [\"...\"]}`.\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  The run goes back to \"in progress\"; poll again to retrieve the new\n  `pending_reviews` entry once it's ready. `output` is ignored.\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`, or an empty `output` (nothing kept), when\n  decision is `approve`.\n- `404`: Run not found, or no pending review with that ID on this run.\n- `409`: The review is no longer waiting (already submitted, or the run\n  finished/failed/was canceled).","operationId":"submit_review_runs__run_id__reviews__review_id__post","parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Run Id"}},{"name":"review_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Review 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"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitReviewRequest"}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
````