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

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

List runs of a Workflow. Workflows are sequences of steps that process files and data in a specific order to achieve a desired outcome. A WorkflowRun represents a single execution of a workflow against a file.


Reference: https://docs.extend.ai/api-reference/endpoints/workflow/list-workflow-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 workflow run: * `"PENDING"` - The workflow run is waiting to be processed * `"PROCESSING"` - The workflow run is currently processing * `"NEEDS_REVIEW"` - The workflow run requires manual review * `"REJECTED"` - The workflow run was rejected during review * `"PROCESSED"` - The workflow run completed successfully * `"FAILED"` - The workflow run encountered an error * `"CANCELLED"` - The workflow run was cancelled * `"CANCELLING"` - The workflow run is being cancelled
  - Allowed values: `PENDING`, `PROCESSING`, `NEEDS_REVIEW`, `REJECTED`, `PROCESSED`, `FAILED`, `CANCELLED`, `CANCELLING`
- `workflowId` (string, optional) — Filters workflow runs by the workflow ID. If not provided, runs for all workflows are returned. Example: `"workflow_BMdfq_yWM3sT-ZzvCnA3f"`
- `batchId` (string, optional) — Filters workflow runs by the batch ID. This is useful for fetching all runs for a given batch created via the [Batch Run Workflow](https://docs.extend.ai/2026-02-09/api-reference/endpoints/workflow/batch-create-workflow-runs) endpoint. Example: `"batch_7Ws31-F5"`
- `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 workflow run. These are shortened versions of the full WorkflowRun object. To get the full object, use the [Get WorkflowRun](https://docs.extend.ai/2026-02-09/api-reference/endpoints/workflow/get-workflow-run) endpoint.

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

### WorkflowRunSummary

- `object` (enum, required) — The type of object. In this case, it will always be `"workflow_run"`.
  - Allowed values: `workflow_run`
- `id` (string, required) — The ID of the workflow run. Example: `"workflow_run_Zk9mNP12Qw4-yTv8BdR3H"`
- `status` (enum, required) — The status of a workflow run: * `"PENDING"` - The workflow run is waiting to be processed * `"PROCESSING"` - The workflow run is currently processing * `"NEEDS_REVIEW"` - The workflow run requires manual review * `"REJECTED"` - The workflow run was rejected during review * `"PROCESSED"` - The workflow run completed successfully * `"FAILED"` - The workflow run encountered an error * `"CANCELLED"` - The workflow run was cancelled * `"CANCELLING"` - The workflow run is being cancelled
  - Allowed values: `PENDING`, `PROCESSING`, `NEEDS_REVIEW`, `REJECTED`, `PROCESSED`, `FAILED`, `CANCELLED`, `CANCELLING`
- `workflow` (WorkflowSummary, required) — A summary representation of a workflow.
- `workflowVersion` (WorkflowVersionSummary, required) — A summary representation of a workflow version (without steps).
- `dashboardUrl` (string, required) — A URL to view this workflow run in the Extend dashboard. Example: `"https://dashboard.extend.ai/workflows/workflow_run_xKm9pNv3qWsY_jL2tR5Dh"`
- `reviewedByUser` (string, required, nullable) — The user of the person who reviewed the workflow run. Will be null if the workflow run has not been reviewed. Example: `"jane.doe@example.com"`
- `reviewedAt` (string, required, nullable) — The time (in UTC) at which the workflow run was reviewed. Will follow the RFC 3339 format. Will be null if the workflow run has not been reviewed. Example: `"2024-03-21T16:45:00Z"`
- `initialRunAt` (string, required, nullable) — The time (in UTC) at which the workflow was initially created. Will follow the RFC 3339 format. Will be null if the run hasn't started yet. Example: `"2024-03-21T15:30:00Z"`
- `startTime` (string, required, nullable) — The start time (in UTC) that the workflow actually started executing. This occurs after the `initialRunAt` time. Will follow the RFC 3339 format. Will be null if not started. Example: `"2024-03-21T15:30:00Z"`
- `endTime` (string, required, nullable) — The end time (in UTC) that the workflow finished. Will follow the RFC 3339 format. Will be null if not finished. Example: `"2024-03-21T15:35:00Z"`
- `batchId` (string, required, nullable) — The batch ID of the workflow run. If that workflow run was created from a batch of files, all runs in that batch will have the same batch ID. Example: `"batch_7Ws31-F5"`
- `rejectionNote` (string, required, nullable) — The note that was added when the workflow run was rejected. Example: `"Invalid invoice format"`
- `files` (list of FileSummary, required) — The input files that this workflow run was executed on. Provided directly on the list response so you don't need to fetch each run individually to inspect its input.
- `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"`
- `usage` (RunUsageSummary, required, nullable) — Usage credits consumed by this workflow run. Omits `breakdown` — fetch the full workflow run by id to see the per-line items for every contributing child run. **Availability:** Will not be returned for runs created before October 7, 2025 or for customers on legacy billing systems.

### WorkflowSummary

A summary representation of a workflow.

- `object` (enum, required) — The type of object. Always `"workflow"`.
  - Allowed values: `workflow`
- `id` (string, required) — The ID of the workflow.
- `name` (string, required) — The name of the workflow.
- `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"`
- `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.

### WorkflowVersionSummary

A summary representation of a workflow version (without steps).

- `object` (enum, required) — The type of object. Always `"workflow_version"`.
  - Allowed values: `workflow_version`
- `id` (string, required) — The ID of the workflow version.
- `version` (string, required) — The version number as a string, or `"draft"` for the draft version.
- `name` (string, required, nullable) — The name of the workflow version.
- `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": "workflow_run",
      "id": "string",
      "status": "PENDING",
      "workflow": {
        "object": "workflow",
        "id": "workflow_BMlfq_yWM3sT-ZzvCnA3f",
        "name": "Invoice Processing",
        "createdAt": "2024-03-21T16:45:00Z",
        "updatedAt": "2024-03-21T16:45:00Z",
        "createdBy": {
          "type": "user",
          "email": "matt@extend.app"
        }
      },
      "workflowVersion": {
        "object": "workflow_version",
        "id": "workflow_version_Zk9mNP12Qw4-yTv8BdR3H",
        "version": "1",
        "name": "Production v1",
        "createdAt": "2024-03-21T16:45:00Z",
        "createdBy": {
          "type": "user",
          "email": "matt@extend.app"
        }
      },
      "dashboardUrl": "https://dashboard.extend.ai/workflows/workflow_run_xKm9pNv3qWsY_jL2tR5Dh",
      "reviewedByUser": "string",
      "reviewedAt": "2024-01-15T09:30:00Z",
      "initialRunAt": "2024-01-15T09:30:00Z",
      "startTime": "2024-01-15T09:30:00Z",
      "endTime": "2024-01-15T09:30:00Z",
      "batchId": "string",
      "rejectionNote": "string",
      "files": [
        {
          "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"
        }
      ],
      "createdAt": "2024-03-21T16:45:00Z",
      "updatedAt": "2024-03-21T16:45:00Z",
      "usage": {
        "credits": 9,
        "totalCredits": 15
      }
    }
  ],
  "nextPageToken": "xK9mLPqRtN3vS8wF5hB2cQ==:zWvUxYjM4nKpL7aDgE9HbTcR2mAyX3/Q+CNkfBSw1dZ="
}
```