Runs

Runs are executions of agents. The typical workflow: discover an agent, 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 agent executions.

List Runs

get

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.

Authorizations

APIKeyHeader

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/runs/

HTTPcURLJavaScriptPython

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

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "agent_id": "123e4567-e89b-12d3-a456-426614174000",
      "external_id": "text",
      "status": "in_progress",
      "progress": 0,
      "awaiting_human_review": false,
      "created_at": "2026-07-16T14:50:13.492Z",
      "started_at": "2026-07-16T14:50:13.492Z",
      "completed_at": "2026-07-16T14:50:13.492Z",
      "cost": 1
    }
  ],
  "has_more": true,
  "next_cursor": "text"
}

Create Run

post

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):

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

Asset Inputs (image_input, video_input, file_input types):

{
    "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:

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"}
# ]

1. Upload assets if needed:

POST /assets/upload
# Response: {"id": "asset-uuid-123", ...}

1. Create run with matching inputs:

{
    "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

Authorizations

APIKeyHeader

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Body

application/json

Request to create and start a new agent execution run.

agent_idstring · uuidRequired

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

Responses

201

Successful Response

application/json

Complete representation of an agent execution run.

idstring · uuidRequired

Unique run identifier

agent_idstring · uuidRequired

ID of the agent 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

awaiting_human_reviewbooleanOptional

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

Default: false

created_atstring · date-timeRequired

When the run was created

started_atstring · date-time · nullableOptional

When execution started

completed_atstring · date-time · nullableOptional

When 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/runs/

HTTPcURLJavaScriptPython

POST /api/public/v1/runs/ HTTP/1.1
Host: api.pletor.ai
Content-Type: application/json
Accept: */*
Content-Length: 166

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

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

Get Run

get

Get detailed information about a specific 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

Authorizations

APIKeyHeader

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 agent execution run.

idstring · uuidRequired

Unique run identifier

agent_idstring · uuidRequired

ID of the agent 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

awaiting_human_reviewbooleanOptional

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

Default: false

created_atstring · date-timeRequired

When the run was created

started_atstring · date-time · nullableOptional

When execution started

completed_atstring · date-time · nullableOptional

When 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/runs/{run_id}

HTTPcURLJavaScriptPython

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

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

Cancel Run

delete

Cancel an ongoing 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

Authorizations

APIKeyHeader

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

HTTPcURLJavaScriptPython

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

No content

Submit Review

post

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:

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

Discard some of the proposed assets by approving with only the kept subset:

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

Retry to regenerate the upstream output:

{"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).

Authorizations

APIKeyHeader

Path parameters

run_idstring · uuidRequired

review_idstring · uuidRequired

Header parameters

X-Organization-Idstring · nullableOptional

Active organization ID for multi-org support

Body

application/json

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.

Possible values:

outputany of · nullableOptional

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.

or

or

stringOptional

Responses

204

Successful Response

No content

422

Validation Error

application/json

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

HTTPcURLJavaScriptPython

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

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

No content