---
title: "List Runs"
method: GET
path: "/runs/"
tags: ["runs"]
---

# List Runs

`GET /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.

## Query parameters

- `status` 'in_progress' | 'completed' | 'failed' | 'canceled' — Execution status of a workflow run.
- `external_id` string, nullable
- `limit` integer — Maximum number of items to return
- `cursor` string, nullable — Cursor for pagination (from next_cursor)

## Headers

- `X-Organization-Id` string, nullable — Active organization ID for multi-org support

## Response `200`

Successful Response

- CursorPaginatedResponseRunSummary
  - `data` RunSummary[], required
    - `id` string, uuid, required — Unique run identifier
    - `agent_id` string, uuid, required — ID of the agent that was executed
    - `external_id` string, nullable — Client-supplied reference id provided at creation, if any
    - `status` 'in_progress' | 'completed' | 'failed' | 'canceled', required — Execution status of a workflow run.
    - `progress` number — Completion progress from 0.0 to 1.0
    - `awaiting_human_review` boolean — True when the run has paused on one or more human review nodes. Fetch GET /runs/{run_id} to inspect pending reviews.
    - `created_at` string, date-time, required — When the run was created
    - `started_at` string, date-time, nullable — When execution started
    - `completed_at` string, date-time, nullable — When execution finished
    - `cost` integer, nullable — Total credits consumed by this run
  - `has_more` boolean, required
  - `next_cursor` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/pletor/apis/pletor-public-api.md) · [All operations](https://skmtc.dev/pletor/apis/pletor-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pletor/pletor-public-api/revisions/e5c350c02ffb/schema)