> This page is for version v2026-02-09 (default).
> For other versions, use one of these documentation indexes:
> - v2026-02-09 (default): https://docs.extend.ai/2026-02-09/llms.txt
> - v2025-04-21: https://docs.extend.ai/2025-04-21/llms.txt
> - v2024-12-23: https://docs.extend.ai/2024-12-23/llms.txt

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extend.ai/llms.txt
> Use this file to discover all available pages before exploring further.
>
> ## API version
> The current API version is `2026-02-09`, served at the site root (no version prefix in URLs).
> If this page URL contains `/2025-04-21/` or `/2024-12-23/`, you are reading an older API version.
> Prefer the current docs at https://docs.extend.ai/llms.txt unless the user explicitly needs that older version.
> Do not treat older-version pages as the source of truth for new integrations.

# List Processor Runs

GET https://api.extend.ai/processor_runs

List runs of a Processor. A ProcessorRun represents a single execution of a processor against a file.


Reference: https://docs.extend.ai/api-reference/endpoints/legacy/list-processor-runs

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://api.extend.ai` (Production, default)
- `https://api.us2.extend.app` (Production US2)
- `https://api.eu1.extend.ai` (Production EU1)

## Request

### Query parameters

- `status` (enum, optional) — Filters processor runs by their status. If not provided, no filter is applied. The status of a processor run: * `"PENDING"` - The processor run has not started yet * `"PROCESSING"` - The processor run is in progress * `"PROCESSED"` - The processor run completed successfully * `"FAILED"` - The processor run encountered an error * `"CANCELLED"` - The processor run was cancelled
  - Allowed values: `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELLED`
- `processorId` (string, optional) — Filters processor runs by the processor ID. If not provided, runs for all processors are returned. Example: `"ex_BMdfq_yWM3sT-ZzvCnA3f"`
- `processorType` (enum, optional) — Filters processor runs by the processor type. If not provided, runs for all processor types are returned. Example: `"EXTRACT"`
  - Allowed values: `EXTRACT`, `CLASSIFY`, `SPLITTER`
- `sourceId` (string, optional) — Filters processor runs by the source ID. The source ID corresponds to the entity that created the processor run. Example: `"workflow_run_123"`
- `source` (enum, optional) — Filters processor runs by the source that created them. If not provided, runs from all sources are returned. The source of the processor run: * `"ADMIN"` - Created by admin * `"BATCH_PROCESSOR_RUN"` - Created from a batch processor run * `"PLAYGROUND"` - Created from playground * `"WORKFLOW_CONFIGURATION"` - Created from workflow configuration * `"WORKFLOW_RUN"` - Created from a workflow run * `"STUDIO"` - Created from Studio * `"API"` - Created via API
  - Allowed values: `ADMIN`, `BATCH_PROCESSOR_RUN`, `PLAYGROUND`, `WORKFLOW_CONFIGURATION`, `WORKFLOW_RUN`, `STUDIO`, `API`
- `fileNameContains` (string, optional) — Filters processor runs by the name of the file. Only returns processor runs where the file name contains this string. Example: `"invoice"`
- `sortBy` (enum, optional, default: updatedAt) — Sorts the processor runs by the given field.
  - Allowed values: `updatedAt`, `createdAt`
- `sortDir` (enum, optional, default: desc) — Sorts the processor runs in ascending or descending order. Ascending order means the earliest processor run is returned first.
  - Allowed values: `asc`, `desc`
- `nextPageToken` (string, optional) — The token used to fetch the page of results from a previous request. We use cursor based pagination and will return a `nextPageToken` in the response if there are more results. Note that if other parameters are changed in subsequent requests, you may receive inconsistent data. example: `"xK9mLPqRtN3vS8wF5hB2cQ==:zWvUxYjM4nKpL7aDgE9HbTcR2mAyX3/Q+CNkfBSw1dZ="`
- `maxPageSize` (integer, optional, default: 10) — The maximum number of results to return in the response. You may receive less than this number if there are fewer results than the maximum.

### Headers

- `x-extend-api-version` ("2026-02-09", optional, default: 2026-02-09) — API version to use for the request. If you're using an SDK, you can ignore this parameter. If you are not using an SDK and do not specify a version, you will either receive a `400 Bad Request` or be set to a previous legacy version. See [API Versioning](https://docs.extend.ai/2026-02-09/api-reference/api-versioning) for more details.
- `x-extend-workspace-id` (string, optional) — The workspace ID to target. **Required** when using an organization-scoped API key; optional for workspace-scoped keys (the key is already tied to a workspace). See [Authentication](https://docs.extend.ai/2026-02-09/api-reference/authentication) for details on API key scopes.

## Response

### 200

You will get a list of summaries for each processor run. These are shortened versions of the full ProcessorRun object. To get the full object, use the [Get ProcessorRun](https://docs.extend.ai/2026-02-09/api-reference/endpoints/legacy/get-processor-run) endpoint.

- `success` (boolean, required)
- `processorRuns` (list of LegacyProcessorRunSummary, required)
- `nextPageToken` (string, optional) — The token used to fetch the page of results from a previous request. We use cursor based pagination and will return a `nextPageToken` in the response if there are more results. Note that if other parameters are changed in subsequent requests, you may receive inconsistent data. example: `"xK9mLPqRtN3vS8wF5hB2cQ==:zWvUxYjM4nKpL7aDgE9HbTcR2mAyX3/Q+CNkfBSw1dZ="`

## Errors

### 400 Bad Request Error

Bad Request

- `success` (boolean, optional)
- `error` (string, optional) — Error message

### 401 Unauthorized Error

Unauthorized

- `success` (boolean, optional)
- `error` (string, optional) — Error message

## Types

### LegacyProcessorRunSummary

- `id` (string, required) — The ID of the processor run. Example: `"exr_Zk9mNP12Qw4-yTv8BdR3H"`
- `status` (enum, required) — The status of a processor run: * `"PENDING"` - The processor run has not started yet * `"PROCESSING"` - The processor run is in progress * `"PROCESSED"` - The processor run completed successfully * `"FAILED"` - The processor run failed * `"CANCELLED"` - The processor run was cancelled
  - Allowed values: `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELLED`
- `processorId` (string, required) — The ID of the processor that was run. Will always start with "ex_". Example: `"ex_BMdfq_yWM3sT-ZzvCnA3f"`
- `processorName` (string, required) — The name of the processor that was run. Example: `"Invoice Extractor"`
- `processorVersionId` (string, required) — The ID of the processor version that was run. Will always start with "exv_". Example: `"exv_Zk9mNP12Qw4-yTv8BdR3H"`
- `createdAt` (string, required) — The time (in UTC) at which the processor run was created. Will follow the RFC 3339 format. Example: `"2024-03-21T15:29:55Z"`
- `updatedAt` (string, required) — The time (in UTC) at which the processor run was last updated. Will follow the RFC 3339 format. Example: `"2024-03-21T16:45:00Z"`
- `type` (enum, optional) — The type of processor that was run: * `"EXTRACT"` - Extraction processor * `"SPLITTER"` - Splitting processor * `"CLASSIFY"` - Classification processor
  - Allowed values: `EXTRACT`, `SPLITTER`, `CLASSIFY`
- `usage` (LegacyDocumentProcessorRunCredits, optional) — These are usage credits for document processing (extraction, classification, or splitting). File parsing credits are tracked separately and can be retrieved from the [Get File](https://docs.extend.ai/2026-02-09/api-reference/endpoints/file/get-file) endpoint. This field will not be returned for processor runs created before October 7, 2025, or for customers on legacy billing systems. For more details on how credits work, see our [Credits Guide](https://docs.extend.ai/general/how-credits-work).

### LegacyDocumentProcessorRunCredits

These are usage credits for document processing (extraction, classification, or splitting). File parsing credits are tracked separately and can be retrieved from the [Get File](https://docs.extend.ai/2026-02-09/api-reference/endpoints/file/get-file) endpoint. This field will not be returned for processor runs created before October 7, 2025, or for customers on legacy billing systems. For more details on how credits work, see our [Credits Guide](https://docs.extend.ai/general/how-credits-work).

- `credits` (double, required) — The number of credits consumed specifically for document processing in this processor run. This does not include file parsing credits.

## Examples

**Response**

```json
{
  "success": true,
  "processorRuns": [
    {
      "id": "string",
      "status": "PENDING",
      "processorId": "string",
      "processorName": "string",
      "processorVersionId": "string",
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z",
      "type": "EXTRACT",
      "usage": {
        "credits": 3.5
      }
    }
  ],
  "nextPageToken": "xK9mLPqRtN3vS8wF5hB2cQ==:zWvUxYjM4nKpL7aDgE9HbTcR2mAyX3/Q+CNkfBSw1dZ="
}
```