App Runs

App runs are executions of apps. The workflow mirrors agent 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. Agent 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
has_more: Indicates if there are more results available
next_cursor: Cursor for the next page of results

Authorizations

Query parameters

statusstring · enum · nullableOptional

Execution status of a workflow run.

Possible values:

external_idstring · nullableOptional

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

application/json

get/app-runs/

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

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "app_id": "123e4567-e89b-12d3-a456-426614174000",
      "external_id": "text",
      "status": "in_progress",
      "progress": 0,
      "created_at": "2026-07-17T02:03:13.681Z",
      "started_at": "2026-07-17T02:03:13.681Z",
      "completed_at": "2026-07-17T02:03:13.681Z",
      "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.

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 (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 /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, brand, or file
- required: whether the input is mandatory
- options / min_selections / max_selections: constraints for fixed-set inputs

Text Inputs:

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

Asset Inputs (image / video / audio / file):

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

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

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 completed run's results contain only the app's curated outputs — never the underlying flow's internal nodes.

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, missing required inputs, or values outside constraints
404: App not found or not accessible

Authorizations

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

Possible values:

progressnumber · max: 1Optional

Completion progress from 0.0 to 1.0

Default: 0

current_nodestring · nullableOptional

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

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

costinteger · nullableOptional

Total credits consumed by this run

errorstring · nullableOptional

Error message if the run failed

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.

Possible values:

422

Validation Error

application/json

post/app-runs/

POST /api/public/v1/app-runs/ HTTP/1.1
Host: api.pletor.ai
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",
  "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"
    }
  ],
  "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
Stop polling when status becomes "completed", "failed", or "canceled"
Extract results from the results array when status is "completed"

How to Retrieve Results: Call GET /apps/{app_id} and examine the outputs array, then match results to outputs by id. Asset results (images/videos/audio/files) are arrays of asset UUIDs — resolve each via GET /assets/{id} and fetch the url field.

Error Codes:

404: Run not found or not accessible

Authorizations

Path parameters

run_idstring · uuidRequired

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

Possible values:

progressnumber · max: 1Optional

Completion progress from 0.0 to 1.0

Default: 0

current_nodestring · nullableOptional

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

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

costinteger · nullableOptional

Total credits consumed by this run

errorstring · nullableOptional

Error message if the run failed

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.

Possible values:

422

Validation Error

application/json

get/app-runs/{run_id}

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

{
  "app_id": "550e8400-e29b-41d4-a716-446655440000",
  "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"
    }
  ],
  "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 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

Authorizations

Path parameters

run_idstring · uuidRequired

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Responses

204

Successful Response

No content

422

Validation Error

application/json

delete/app-runs/{run_id}

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

No content

PreviousRuns NextAssets

Last updated 20 days ago