> 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 Parse Runs

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

List parse runs, with optional filters for status, batch ID, source, and file name.

Returns a paginated list of parse runs. Use `GET /parse_runs/{id}` to retrieve the full result including output for a specific run.

Reference: https://docs.extend.ai/api-reference/endpoints/parse/list-parse-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) — Filter parse runs by status.
  - Allowed values: `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`
- `batchId` (string, optional) — Filter parse runs by the batch they belong to. Use this after submitting a batch via `POST /parse_runs/batch` to retrieve individual run results. Example: `"bpar_Xj8mK2pL9nR4vT7qY5wZ"`
- `source` (enum, optional) — Filters parse runs by the source that created them. If not provided, runs from all sources are returned. **Note:** When `batchId` is provided, it takes precedence and this filter is ignored.
  - Allowed values: `API`, `STUDIO`, `WORKFLOW_RUN`, `ADMIN`, `BATCH_PARSER_RUN`, `EDIT_RUN`, `DOCUMENT_PROCESSOR_RUN`
- `sourceId` (string, optional) — Filters runs by the source ID.
- `fileNameContains` (string, optional) — Filters runs by the name of the file. Only returns runs where the file name contains this string. Example: `"invoice"`
- `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.
- `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

Successfully retrieved parse runs

- `object` (enum, required)
  - Allowed values: `list`
- `data` (list of ParseRunSummary, 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.

## Errors

### 400 Bad Request Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 401 Unauthorized Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 402 Payment Required Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 403 Forbidden Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 404 Not Found Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 422 Unprocessable Entity Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 429 Too Many Requests Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

### 500 Internal Server Error

Standard error response format for all Extend API errors. See the [Error Codes documentation](https://docs.extend.ai/2026-02-09/api-reference/error-handling) for error handling recommendations.

- `code` (string, required) — Error code for programmatic handling.
- `message` (string, required) — Human-readable error message suitable for displaying to developers. Do not rely on the exact text of this message as it may change.
- `retryable` (boolean, required) — Whether the request can be retried. When true, retry with exponential backoff. When false, fix the underlying issue before retrying.
- `requestId` (string, optional) — Unique request identifier for support purposes. Always include this when contacting Extend support about an error.
- `docUrl` (string, optional) — Link to relevant documentation when one is available.

## Types

### ParseRunSummary

Summary representation of a parse run.

- `object` (enum, required) — The type of object. Will always be `"parse_run"`.
  - Allowed values: `parse_run`
- `id` (string, required) — A unique identifier for the parse run. Example: `"pr_xK9mLPqRtN3vS8wF5hB2cQ"`
- `batchId` (string, required, nullable) — The ID of the batch this run belongs to, if created via `POST /parse_runs/batch`. **Availability:** Present when the run was submitted as part of a batch. Example: `"bpar_Xj8mK2pL9nR4vT7qY5wZ"`
- `file` (FileSummary, required, nullable) — The file that was parsed. This file can be used as a parameter for other Extend endpoints, such as `POST /workflow_runs`. May be `null` for batch parse runs where file ingestion failed.
- `status` (enum, required) — The status of the parse run: * `"PENDING"` - The run has been created and is waiting to be processed. Only applies to runs created via `POST /parse_runs/batch`. * `"PROCESSING"` - The file is still being processed * `"PROCESSED"` - The file was successfully processed * `"FAILED"` - The processing failed (see `failureReason` for details)
  - Allowed values: `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`
- `failureReason` (string, required, nullable) — The reason for failure. **Availability:** Present when `status` is `"FAILED"`. Possible values include: * `UNABLE_TO_DOWNLOAD_FILE` - The file could not be downloaded from the provided URL * `FILE_TYPE_NOT_SUPPORTED` - The file type is not supported for parsing * `FILE_SIZE_TOO_LARGE` - The file exceeds the maximum allowed size * `CORRUPT_FILE` - The file appears to be corrupted or malformed * `OCR_ERROR` - An error occurred during optical character recognition * `PASSWORD_PROTECTED_FILE` - The file is password protected and cannot be processed * `FAILED_TO_CONVERT_TO_PDF` - The file could not be converted to PDF for processing * `FAILED_TO_CONVERT_TO_JPEG` - The file could not be converted to JPEG for processing * `FAILED_TO_GENERATE_TARGET_FORMAT` - The output could not be generated in the requested format * `CHUNKING_ERROR` - An error occurred while chunking the document * `INTERNAL_ERROR` - An unexpected internal error occurred * `INVALID_CONFIG_OPTIONS` - The provided configuration options are invalid * `OUT_OF_CREDITS` - Insufficient credits to process the file **Note:** Additional failure reasons may be added in the future. Your integration should handle unknown values gracefully.
- `failureMessage` (string, required, nullable) — A human-readable description of the failure. **Availability:** Present when `status` is `"FAILED"`.
- `metadata` (map from string to any, required, nullable) — Any metadata that was provided when creating the parse run. **Availability:** Present when metadata was provided during creation.
- `metrics` (ParseRunSummaryMetrics, required, nullable) — Metrics about the parsing process. **Availability:** Present when `status` is `"PROCESSED"`.
- `usage` (RunUsageSummary, required, nullable) — Usage credits consumed by this parse run. Omits `breakdown` — fetch the full parse run by id to see the per-line items. **Availability:** Present when `status` is `"PROCESSED"`, the run was created after October 7, 2025, and the customer is on the current billing system.
- `createdAt` (string, required) — The time (in UTC) at which the object was created. Will follow the RFC 3339 format. Example: `"2024-03-21T16:45:00Z"`
- `updatedAt` (string, required) — The time (in UTC) at which the object was last updated. Will follow the RFC 3339 format. Example: `"2024-03-21T16:45:00Z"`

### FileSummary

- `object` (enum, required) — The type of object. Will always be `"file"`.
  - Allowed values: `file`
- `id` (string, required) — ID for the file. Example: `"file_xK9mLPqRtN3vS8wF5hB2cQ"`
- `name` (string, required) — The name of the file Example: `"Invoices.pdf"`
- `type` (enum, required, nullable) — The type of the file. **Availability:** Present when the file type could be determined.
  - Allowed values: `PDF`, `CSV`, `IMG`, `TXT`, `DOCX`, `EXCEL`, `XML`, `HTML`
- `parentFileId` (string, required, nullable) — ID of the parent file. **Availability:** Present for files created via a Splitter in a workflow.
- `metadata` (FileMetadata, required)
- `createdAt` (string, required) — The time (in UTC) at which the object was created. Will follow the RFC 3339 format. Example: `"2024-03-21T16:45:00Z"`
- `updatedAt` (string, required) — The time (in UTC) at which the object was last updated. Will follow the RFC 3339 format. Example: `"2024-03-21T16:45:00Z"`

### ParseRunSummaryMetrics

Metrics about the parsing process. **Availability:** Present when `status` is `"PROCESSED"`.

- `processingTimeMs` (double, required) — The time taken to process the document in milliseconds.
- `pageCount` (double, required) — The number of pages from the document that were parsed. For PDF and image files, this is the actual page count. For spreadsheet files (Excel, CSV), this is an estimated page count based on content volume (~1000 tokens per page).

### RunUsageSummary

Usage credits consumed by a run. Omits `breakdown` - fetch the full resource by id when you need the breakdown. **Availability:** This field will not be returned for: * Runs created before October 7, 2025 * 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 credits consumed by this run. For most run types this is the line item for the run's own work; for `workflow_run` this is the aggregate across all child runs.
- `totalCredits` (double, optional) — The total credits accounted for under this run, including any other runs it was responsible for creating. For example, an extract run on a fresh upload triggers a parse run, so `totalCredits` includes both line items. For runs that didn't trigger any other work — like `parse_run`, `edit_run`, and `workflow_run` — `totalCredits` equals `credits`. **Availability:** Present on runs persisted on or after May 14, 2026. Runs persisted before that date will omit this field.

### FileMetadata

- `pageCount` (double, optional) — The number of pages in the file. This is only set for PDF/DOCX files.
- `parentSplit` (ParentSplit, optional) — The split metadata details for a derivative file. **Availability:** Only included if this file is a derivative of another file, for instance if it was created via a Splitter in a workflow.

### ParentSplit

The split metadata details for a derivative file. **Availability:** Only included if this file is a derivative of another file, for instance if it was created via a Splitter in a workflow.

- `id` (string, required) — The ID of the split.
- `type` (string, required) — The type of the split.
- `identifier` (string, required) — The identifier of the split.
- `startPage` (integer, required) — The start page of the split.
- `endPage` (integer, required) — The end page of the split.

## Examples

**Response**

```json
{
  "object": "list",
  "data": [
    {
      "object": "parse_run",
      "id": "pr_xK9mLPqRtN3vS8wF5hB2cQ",
      "batchId": "bpar_Xj8mK2pL9nR4vT7qY5wZ",
      "file": {
        "object": "file",
        "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
        "name": "Invoices.pdf",
        "type": "PDF",
        "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H",
        "metadata": {
          "pageCount": 30,
          "parentSplit": {
            "id": "string",
            "type": "Invoice",
            "identifier": "other_2_9",
            "startPage": 1,
            "endPage": 10
          }
        },
        "createdAt": "2024-03-21T16:45:00Z",
        "updatedAt": "2024-03-21T16:45:00Z"
      },
      "status": "PENDING",
      "failureReason": "FILE_TYPE_NOT_SUPPORTED",
      "failureMessage": "File type not supported for parsing.",
      "metadata": {},
      "metrics": {
        "processingTimeMs": 1234,
        "pageCount": 5
      },
      "usage": {
        "credits": 9,
        "totalCredits": 15
      },
      "createdAt": "2024-03-21T16:45:00Z",
      "updatedAt": "2024-03-21T16:45:00Z"
    }
  ],
  "nextPageToken": "xK9mLPqRtN3vS8wF5hB2cQ==:zWvUxYjM4nKpL7aDgE9HbTcR2mAyX3/Q+CNkfBSw1dZ="
}
```