App Runs

App runs are executions of apps. The workflow mirrors runs: discover an app, inspect its required inputs, upload any necessary assets, create a run with matching inputs, poll its status, and retrieve the app's curated outputs once complete.

Create, monitor, and cancel app executions.

List App Runs

get

List app execution runs with filtering options.

This endpoint returns a paginated list of app execution runs with their current status and basic metadata, newest first. It covers every app run in the caller's organization, whoever started it. Flow runs are listed separately via GET /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 app-run summaries with basic information. Summaries carry no inputs, results or pending_reviews — fetch GET /app-runs/{run_id}
has_more: Indicates if there are more results available
next_cursor: Cursor for the next page of results

Error Codes:

401: Missing or invalid API key or Bearer token
403: The API key is bound to a different organization than X-Organization-Id
422: Invalid status value, or limit outside 1–100
429: Rate limit exceeded — retry after the Retry-After header

Authorizations

X-Api-KeystringRequired

API key for authentication

Query parameters

statusstring · enum · nullableOptional

Only return runs in this status

Possible values:

external_idstring · nullableOptional

Only return the run created with this external_id

limitinteger · min: 1 · max: 100Optional

Maximum number of items to return

Default: 20

cursorstring · nullableOptional

Cursor for pagination (from next_cursor)

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses

200

Successful Response

application/json

has_morebooleanRequired

next_cursorstring · nullableOptional

422

Validation error (validation_error)

application/json

get/app-runs/

GET /api/public/v1/app-runs/ HTTP/1.1
Host: api.pletor.ai
X-Api-Key: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "app_id": "123e4567-e89b-12d3-a456-426614174000",
      "external_id": "text",
      "status": "in_progress",
      "progress": 0,
      "awaiting_human_review": false,
      "created_at": "2026-01-01T00:00:00.000Z",
      "started_at": "2026-01-01T00:00:00.000Z",
      "completed_at": "2026-01-01T00:00:00.000Z",
      "cost": 1
    }
  ],
  "has_more": true,
  "next_cursor": "text"
}

Create App Run

post

Create and start a new app execution run.

This endpoint launches the execution of an app with the provided inputs. The execution runs asynchronously, allowing you to monitor progress and retrieve results when complete. The run executes the flow version pinned by the app's latest version and starts with status in_progress.

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 /app-runs?external_id=.... The id is echoed on every app-run response.

Scope: per organization, across all runs (flow and app share the key space) and all statuses — a key, once used, stays used.
On 409, do not keep retrying the create; GET /app-runs?external_id= to retrieve the existing run. To start a genuinely new run, use a new external_id.

How to Build Inputs:

First, get app details: Call GET /apps/{app_id} to retrieve the app configuration.
Examine the inputs array: Each object defines what input the app expects:
- id: Use this as the id in your input object
- type: text, image, video, audio, or file
- required: whether the input is mandatory
- options / min_selections / max_selections: constraints for fixed-set inputs

Text Inputs: a string, or a list of strings (each string counts as one selection against min_selections / max_selections; with options, each must be one of the listed labels).

{"id": "text_input_node_id", "value": "Your text content here"}

Asset Inputs (image / video / audio / file): an object with asset_ids (a bare list of asset IDs is also accepted). With options, each ID must be one of the listed asset IDs.

{"id": "image_input_node_id", "value": {"asset_ids": ["uuid1", "uuid2"]}}

Upload assets first via POST /assets/upload to get the UUIDs.

A brand used by the app's flow is not an input: it is fixed on the flow and cannot be passed per run.

Example:

{
    "app_id": "550e8400-e29b-41d4-a716-446655440000",
    "inputs": [
        {"id": "uuid-1", "value": "Create a marketing banner for a tech startup"}
    ]
}

Curated contract: only the inputs advertised by GET /apps/{app_id} are accepted. Unknown input ids, missing required inputs, and values that violate an input's options / min_selections / max_selections are rejected with 400. The run's results contain only the app's curated outputs — never the underlying flow's internal nodes.

Credits: the balance is not checked when the run is created. A run that exhausts the organization's credits or the user's quota fails with failure_reason insufficient_credits.

Response:

AppRun object with execution details and initial status
Use id to monitor progress via GET /app-runs/{run_id}

Error Codes:

400: Invalid input format, unknown input id, missing required inputs, values outside constraints, or an app whose flow has validation errors or no flow definition
401: Missing or invalid API key or Bearer token
403: The API key is bound to a different organization than X-Organization-Id
404: App not found or not accessible
409: external_id already used by another run in this organization
422: Malformed request body (e.g. external_id over 255 characters), or inputs that a node of the flow would reject before running
429: Rate limit exceeded — retry after the Retry-After header

Authorizations

X-Api-KeystringRequired

API key for authentication

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Body

Request to create and start a new app execution run.

app_idstring · uuidRequired

Stable ID of the app to execute

external_idstring · max: 255 · nullableOptional

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 app run and filterable via GET /app-runs?external_id= to fetch it. Use a new id per run.

Responses

201

Successful Response

application/json

Complete representation of an app execution run.

idstring · uuidRequired

Unique run identifier

app_idstring · uuidRequired

Stable ID of the app being executed

external_idstring · nullableOptional

Client-supplied reference id provided at creation, if any

statusstring · enumRequired

Current execution state: in_progress, completed, failed, or canceled. A run starts in_progress and ends in exactly one of the others

Possible values:

progressnumber · max: 1Optional

Fraction of the run's node executions that have completed, from 0.0 to 1.0. 1.0 once completed; 0.0 once failed or canceled

Default: 0

current_nodestring · nullableOptional

Type of the node currently executing (e.g. image_generation, llm). Only present while status is in_progress

awaiting_human_reviewbooleanOptional

True when the run has paused on one or more human review nodes and is waiting for a decision via POST /app-runs/{run_id}/reviews/{review_id}. While true, status remains in_progress. A review left without a decision for 1 week fails the run.

Default: false

created_atstring · date-timeRequired

When the run was created

started_atstring · date-time · nullableOptional

When execution started

completed_atstring · date-time · nullableOptional

When execution finished (completed, failed or canceled). Null while in_progress

costinteger · nullableOptional

Credits consumed by this run so far, summed over its node executions. Null before any node has run

errorstring · nullableOptional

Error message if the run failed or was canceled

failure_reasonstring · enum · nullableOptional

Categorized failure reason (timeout, content_policy, insufficient_credits, invalid_input, provider_error, provider_auth_required, canceled, unknown). Present when status is failed or canceled.

Possible values:

422

Validation error (validation_error)

application/json

post/app-runs/

POST /api/public/v1/app-runs/ HTTP/1.1
Host: api.pletor.ai
X-Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 164

{
  "app_id": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "order-4821",
  "inputs": [
    {
      "id": "text_input_1",
      "value": "Create a marketing banner for a tech startup"
    }
  ]
}

{
  "app_id": "550e8400-e29b-41d4-a716-446655440000",
  "awaiting_human_review": false,
  "created_at": "2026-04-15T10:00:00Z",
  "current_node": "image_generation",
  "external_id": "order-4821",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "inputs": [
    {
      "id": "text_input_1",
      "value": "A futuristic city at sunset"
    }
  ],
  "pending_reviews": [],
  "progress": 0.5,
  "results": [],
  "started_at": "2026-04-15T10:00:01Z",
  "status": "in_progress"
}

Get App Run

get

Get detailed information about a specific app execution run.

This endpoint retrieves comprehensive information about an app run, including real-time status, progress, inputs, and curated results when available.

Monitoring Workflow:

Create run via POST /app-runs
Poll this endpoint to monitor progress
If awaiting_human_review becomes true, inspect pending_reviews and resolve each via POST /app-runs/{run_id}/reviews/{review_id} to resume execution (within 1 week, or the run fails)
Stop polling when status becomes "completed", "failed", or "canceled"
Extract results from the results array when status is "completed"

Progress Tracking:

status: in_progress until the run ends as completed, failed or canceled
progress: Fraction of node executions completed (0.0 to 1.0)
current_node: Type of the node executing now, while in_progress
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

How to Retrieve Results: Call GET /apps/{app_id} and examine the outputs array, then match results to outputs by id. Results appear as each output node finishes, so results can be partial while the run is in_progress or after it fails.

Text results: 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: value is the node's raw output object.

Cost Information:

cost: Credits consumed so far (null before any node has run)

Error Handling:

error: Error message if the run failed or was canceled
failure_reason: Categorized cause, set when status is failed or canceled

Error Codes:

401: Missing or invalid API key or Bearer token
403: The API key is bound to a different organization than X-Organization-Id
404: Run not found in the caller's organization, or it is a flow run (use GET /runs/{run_id})
422: run_id is not a UUID
429: Rate limit exceeded — retry after the Retry-After header

Authorizations

X-Api-KeystringRequired

API key for authentication

Path parameters

run_idstring · uuidRequired

ID of the app run

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses

200

Successful Response

application/json

Complete representation of an app execution run.

idstring · uuidRequired

Unique run identifier

app_idstring · uuidRequired

Stable ID of the app being executed

external_idstring · nullableOptional

Client-supplied reference id provided at creation, if any

statusstring · enumRequired

Current execution state: in_progress, completed, failed, or canceled. A run starts in_progress and ends in exactly one of the others

Possible values:

progressnumber · max: 1Optional

Fraction of the run's node executions that have completed, from 0.0 to 1.0. 1.0 once completed; 0.0 once failed or canceled

Default: 0

current_nodestring · nullableOptional

Type of the node currently executing (e.g. image_generation, llm). Only present while status is in_progress

awaiting_human_reviewbooleanOptional

Default: false

created_atstring · date-timeRequired

When the run was created

started_atstring · date-time · nullableOptional

When execution started

completed_atstring · date-time · nullableOptional

When execution finished (completed, failed or canceled). Null while in_progress

costinteger · nullableOptional

Credits consumed by this run so far, summed over its node executions. Null before any node has run

errorstring · nullableOptional

Error message if the run failed or was canceled

failure_reasonstring · enum · nullableOptional

Categorized failure reason (timeout, content_policy, insufficient_credits, invalid_input, provider_error, provider_auth_required, canceled, unknown). Present when status is failed or canceled.

Possible values:

422

Validation error (validation_error)

application/json

get/app-runs/{run_id}

GET /api/public/v1/app-runs/{run_id} HTTP/1.1
Host: api.pletor.ai
X-Api-Key: YOUR_API_KEY
Accept: */*

{
  "app_id": "550e8400-e29b-41d4-a716-446655440000",
  "awaiting_human_review": false,
  "created_at": "2026-04-15T10:00:00Z",
  "current_node": "image_generation",
  "external_id": "order-4821",
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "inputs": [
    {
      "id": "text_input_1",
      "value": "A futuristic city at sunset"
    }
  ],
  "pending_reviews": [],
  "progress": 0.5,
  "results": [],
  "started_at": "2026-04-15T10:00:01Z",
  "status": "in_progress"
}

Cancel App Run

delete

Cancel an ongoing app execution run.

This endpoint allows you to cancel an execution whose status is in_progress, including one paused on a human review. Once cancelled, the execution cannot be resumed.

Behavior:

The 204 confirms the cancellation was requested; it takes effect asynchronously, usually within a few seconds
Once it lands, GET /app-runs/{run_id} shows status canceled and failure_reason canceled
A run that is already completed, failed or canceled cannot be cancelled and answers 404

Error Codes:

401: Missing or invalid API key or Bearer token
403: The API key is bound to a different organization than X-Organization-Id
404: Run not found in the caller's organization, it is a flow run, or it is no longer in_progress
422: run_id is not a UUID
429: Rate limit exceeded — retry after the Retry-After header

Authorizations

X-Api-KeystringRequired

API key for authentication

Path parameters

run_idstring · uuidRequired

ID of the app run

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses

204

Successful Response

No content

422

Validation error (validation_error)

application/json

delete/app-runs/{run_id}

DELETE /api/public/v1/app-runs/{run_id} HTTP/1.1
Host: api.pletor.ai
X-Api-Key: YOUR_API_KEY
Accept: */*

No content

Submit App Run Review

post

Resolve a pending human review and resume an app execution.

When the app's underlying flow includes a human review step, the run pauses on that node and awaiting_human_review becomes true on GET /app-runs/{run_id}. Each waiting step is listed in the run's pending_reviews array. Submit a decision here to resume. A review left without a decision for 1 week fails the run.

App runs are resolved only here: POST /runs/{run_id}/reviews/{review_id} answers 404 for an app run.

Discovering pending reviews

Poll GET /app-runs/{run_id} until awaiting_human_review is true.
Inspect the pending_reviews array. Use a review's id as review_id in this endpoint's path.
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), and an output whose shape does not match the reviewed node is rejected with 400.
retry: re-run the upstream node(s) to produce a new candidate output. output is ignored. The same review (same id) stays in pending_reviews and awaiting_human_review stays true while the upstream regenerates; its proposed_output is refreshed when that finishes. Wait for the new proposed_output before deciding again — a decision sent earlier is applied as soon as regeneration ends.

Examples

Approve an image review using the proposed assets:

{
    "decision": "approve",
    "output": {
        "asset_ids": [
            "asset-uuid-001",
            "asset-uuid-002"
        ]
    }
}

Retry to regenerate the upstream output:

{"decision": "retry"}

Error Codes:

400: Missing output, an empty output (nothing kept), or an output that does not match the reviewed node's shape, when decision is approve.
401: Missing or invalid API key or Bearer token
403: The API key is bound to a different organization than X-Organization-Id
404: Run not found in the caller's organization, it is a flow run, the caller can no longer read the app, or no human review with that ID on this run.
409: The review is no longer waiting (already submitted, or the run finished/failed/was canceled).
422: Malformed body (e.g. decision not approve or retry) or a path ID that is not a UUID
429: Rate limit exceeded — retry after the Retry-After header

Authorizations

X-Api-KeystringRequired

API key for authentication

Path parameters

run_idstring · uuidRequired

ID of the app run

review_idstring · uuidRequired

id of an entry in the run's pending_reviews

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Body

Request to resolve a pending human review.

decisionstring · enumRequired

approve resumes execution using the (optionally edited) output. retry re-runs the upstream node(s) to produce a new candidate output, then waits for another decision on the same review.

Possible values:

outputany of · nullableOptional

Output to use when continuing execution. Required when decision is approve (missing → 400). Ignored when decision is retry. Must be an object matching the shape of proposed_output ({"asset_ids": [...]} for image/video/audio reviews, {"prompts": [...]} for text reviews — a text node's own key such as texts is also accepted); a mismatched shape is rejected with 400. To discard items, submit only the ones you want to keep; the rest are dropped. At least one item is required — an empty output is rejected with 400.

stringOptional

Responses

204

Successful Response

No content

422

Validation error (validation_error)

application/json

post/app-runs/{run_id}/reviews/{review_id}

POST /api/public/v1/app-runs/{run_id}/reviews/{review_id} HTTP/1.1
Host: api.pletor.ai
X-Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "decision": "approve",
  "output": {
    "asset_ids": [
      "asset-uuid-001",
      "asset-uuid-002"
    ]
  }
}

No content

PreviousRuns

NextAssets

Last updated 20 days ago