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

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

List all classify runs.

Returns a summary of each run. Use `GET /classify_runs/{id}` to retrieve the full object including `output` and `config`.

Reference: https://docs.extend.ai/api-reference/endpoints/classify/list-classify-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) — The status of a processor run (extract, classify, or split): * `"PENDING"` - The run has been created and is waiting to be processed * `"PROCESSING"` - The run is in progress * `"PROCESSED"` - The run completed successfully * `"FAILED"` - The run failed * `"CANCELLED"` - The run was cancelled
  - Allowed values: `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELLED`
- `classifierId` (string, optional) — Filters classify runs by the classifier ID. If not provided, all classify runs are returned. Example: `"cl_BMdfq_yWM3sT-ZzvCnA3f"`
- `batchId` (string, optional) — Filters runs by the batch they belong to. Only returns runs created as part of the specified batch. Example: `"bpr_Xj8mK2pL9nR4vT7qY5wZ"`
- `sourceId` (string, optional) — Filters runs by the source ID.
- `source` (enum, optional) — Filters runs by the source that created them. If not provided, runs from all sources are returned.
  - Allowed values: `ADMIN`, `BATCH_PROCESSOR_RUN`, `PLAYGROUND`, `WORKFLOW_CONFIGURATION`, `WORKFLOW_RUN`, `STUDIO`, `API`
- `fileNameContains` (string, optional) — Filters runs by the name of the file. Only returns runs where the file name contains this string. Example: `"invoice"`
- `sortBy` (enum, optional, default: updatedAt) — Sort by the given field.
  - Allowed values: `updatedAt`, `createdAt`
- `sortDir` (enum, optional, default: desc) — Sort in ascending or descending order. Ascending order means the earliest result 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.
- `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 classify run. These are shortened versions of the full classify run object. To get the full object, use the [Get Classify Run](https://docs.extend.ai/2026-02-09/api-reference/endpoints/classify/get-classify-run) endpoint.

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

### ClassifyRunSummary

Summary representation of a classify run.

- `object` (enum, required) — The type of object. Will always be `"classify_run"`.
  - Allowed values: `classify_run`
- `id` (string, required) — The unique identifier for this classify run.
- `classifier` (ClassifierSummary, required, nullable) — The classifier that was used for this run. **Availability:** Present when a classifier reference was provided. Not present when using inline `config`.
- `classifierVersion` (ClassifierVersionSummary, required, nullable) — The version of the classifier that was used for this run. **Availability:** Present when a classifier reference was provided. Not present when using inline `config`.
- `status` (enum, required) — The status of a processor run (extract, classify, or split): * `"PENDING"` - The run has been created and is waiting to be processed * `"PROCESSING"` - The run is in progress * `"PROCESSED"` - The run completed successfully * `"FAILED"` - The run failed * `"CANCELLED"` - The run was cancelled
  - Allowed values: `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELLED`
- `failureReason` (string, required, nullable) — The reason for failure. **Availability:** Present when `status` is `"FAILED"`.
- `failureMessage` (string, required, nullable) — A detailed message about the failure. **Availability:** Present when `status` is `"FAILED"`.
- `metadata` (map from string to any, required, nullable) — Any metadata that was provided when creating the classify run. **Availability:** Present when metadata was provided during creation.
- `reviewed` (boolean, required) — Indicates whether the run has been reviewed by a human.
- `edited` (boolean, required) — Indicates whether the run results have been edited during review.
- `file` (FileSummary, required, nullable) — The file that was processed. `null` when the file could not be accessed or processed (for example a run that failed during file ingestion, or a multi-file batch run).
- `parseRunId` (string, required, nullable) — The ID of the parse run that was used for this classify run. **Availability:** Present when a parse run was created.
- `dashboardUrl` (string, required) — The URL to view the classify run in the Extend dashboard.
- `usage` (RunUsageSummary, required, nullable) — Usage credits consumed by this classify run. Omits `breakdown` — fetch the full classify run by id to see the per-line items. **Availability:** Present when `status` is `"PROCESSED"`. Will not be returned for runs created before October 7, 2025 or for customers on legacy billing systems.
- `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"`

### ClassifierSummary

- `object` (enum, required) — The type of object. Will always be `"classifier"`.
  - Allowed values: `classifier`
- `id` (string, required) — The ID of the classifier. Example: `"cl_Xj8mK2pL9nR4vT7qY5wZ"`
- `name` (string, required) — The name of the classifier. Example: `"Document Type Classifier"`
- `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"`

### ClassifierVersionSummary

- `object` (enum, required) — The type of object. Will always be `"classifier_version"`.
  - Allowed values: `classifier_version`
- `id` (string, required) — The unique identifier for this version of the classifier. Example: `"clv_xK9mLPqRtN3vS8wF5hB2cQ"`
- `description` (string, required, nullable) — A description of this version of the classifier. Example: `"Added new document types for Q4 processing"`
- `version` (string, required) — The version number or identifier for this specific version of the classifier. The draft version will have version="draft". Examples: `"1.0"`, `"2.1"`, `"draft"`
- `classifierId` (string, required) — The ID of the classifier that this version belongs to. Example: `"cl_Xj8mK2pL9nR4vT7qY5wZ"`
- `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"`
- `createdBy` (CreatedBy, required) — The actor that created this resource. * `user` — the resource was created via the studio by a logged-in user. The user's `email` is exposed. * `api_key` — the resource was created via the API using an API key. The key's `name` is exposed. May be `null` for resources created before attribution.

### 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"`

### 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.

### CreatedBy

The actor that created this resource. * `user` — the resource was created via the studio by a logged-in user. The user's `email` is exposed. * `api_key` — the resource was created via the API using an API key. The key's `name` is exposed. May be `null` for resources created before attribution.

- `type`: `user` (user)
  - `email` (string, required) — The email address of the user who created the resource.
- `type`: `api_key` (api_key)
  - `name` (string, required) — The name of the API key that created the resource.

### 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": "classify_run",
      "id": "clr_Xj8mK2pL9nR4vT7qY5wZ",
      "classifier": {
        "object": "classifier",
        "id": "cl_Xj8mK2pL9nR4vT7qY5wZ",
        "name": "Document Type Classifier",
        "createdAt": "2024-03-21T16:45:00Z",
        "updatedAt": "2024-03-21T16:45:00Z"
      },
      "classifierVersion": {
        "object": "classifier_version",
        "id": "clv_xK9mLPqRtN3vS8wF5hB2cQ",
        "description": "Added new document types for Q4 processing",
        "version": "draft",
        "classifierId": "cl_Xj8mK2pL9nR4vT7qY5wZ",
        "createdAt": "2024-03-21T16:45:00Z",
        "createdBy": {
          "type": "user",
          "email": "matt@extend.app"
        }
      },
      "status": "PROCESSING",
      "failureReason": "PARSING_ERROR",
      "failureMessage": "string",
      "metadata": {},
      "reviewed": false,
      "edited": false,
      "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"
      },
      "parseRunId": "pr_Xj8mK2pL9nR4vT7qY5wZ",
      "dashboardUrl": "https://dashboard.extend.ai/runs/clr_Xj8mK2pL9nR4vT7qY5wZ",
      "usage": {
        "credits": 9,
        "totalCredits": 15
      },
      "createdAt": "2024-03-21T16:45:00Z",
      "updatedAt": "2024-03-21T16:45:00Z"
    }
  ],
  "nextPageToken": "xK9mLPqRtN3vS8wF5hB2cQ==:zWvUxYjM4nKpL7aDgE9HbTcR2mAyX3/Q+CNkfBSw1dZ="
}
```