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

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

List verify runs, with optional filters for status, source, risk level, and file name.

Returns a paginated list of run summaries, each carrying the run's `riskLevel` but not its `output`. Use `GET /verify_runs/{id}` to retrieve the signals and evidence for a specific run.

Reference: https://docs.extend.ai/api-reference/endpoints/verify/list-verify-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 verify runs by status.
  - Allowed values: `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELLED`
- `source` (enum, optional) — Filter verify runs by the source that created them. If not provided, runs from all sources are returned.
  - Allowed values: `API`, `STUDIO`
- `sourceId` (string, optional) — Filter verify runs by `sourceId`. For API-created runs this is the request ID of the creating request.
- `riskLevel` (enum, optional) — Return only processed runs whose result has this risk level. A zero-retention run stops matching once its result has been purged.
  - Allowed values: `LOW`, `MEDIUM`, `HIGH`
- `fileNameContains` (string, optional) — Filters runs by file. A verify run ID (`vr_...`) matches that run, a file ID (`file_...`) matches runs on that file, and any other value matches runs whose file name contains it. Example: `"statement"`
- `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

Successfully retrieved verify runs

- `object` (enum, required)
  - Allowed values: `list`
- `data` (list of VerifyRunSummary, 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.
- `runId` (string, optional) — The ID of the run the error refers to, when the run outlives the request. Currently returned only when a synchronous `POST /verify` request times out: the verify run keeps processing, so fetch it with `GET /verify_runs/{id}` instead of resubmitting the file.

### 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.
- `runId` (string, optional) — The ID of the run the error refers to, when the run outlives the request. Currently returned only when a synchronous `POST /verify` request times out: the verify run keeps processing, so fetch it with `GET /verify_runs/{id}` instead of resubmitting the file.

### 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.
- `runId` (string, optional) — The ID of the run the error refers to, when the run outlives the request. Currently returned only when a synchronous `POST /verify` request times out: the verify run keeps processing, so fetch it with `GET /verify_runs/{id}` instead of resubmitting the file.

### 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.
- `runId` (string, optional) — The ID of the run the error refers to, when the run outlives the request. Currently returned only when a synchronous `POST /verify` request times out: the verify run keeps processing, so fetch it with `GET /verify_runs/{id}` instead of resubmitting the file.

### 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.
- `runId` (string, optional) — The ID of the run the error refers to, when the run outlives the request. Currently returned only when a synchronous `POST /verify` request times out: the verify run keeps processing, so fetch it with `GET /verify_runs/{id}` instead of resubmitting the file.

### 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.
- `runId` (string, optional) — The ID of the run the error refers to, when the run outlives the request. Currently returned only when a synchronous `POST /verify` request times out: the verify run keeps processing, so fetch it with `GET /verify_runs/{id}` instead of resubmitting the file.

### 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.
- `runId` (string, optional) — The ID of the run the error refers to, when the run outlives the request. Currently returned only when a synchronous `POST /verify` request times out: the verify run keeps processing, so fetch it with `GET /verify_runs/{id}` instead of resubmitting the file.

### 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.
- `runId` (string, optional) — The ID of the run the error refers to, when the run outlives the request. Currently returned only when a synchronous `POST /verify` request times out: the verify run keeps processing, so fetch it with `GET /verify_runs/{id}` instead of resubmitting the file.

## Types

### VerifyRunSummary

Summary representation of a verify run, as returned by `GET /verify_runs`. Carries the run's `riskLevel` but not its `output`; use `GET /verify_runs/{id}` for the signals and evidence.

- `object` (enum, required) — The type of object. Will always be `"verify_run"`.
  - Allowed values: `verify_run`
- `id` (string, required) — A unique identifier for the verify run. Example: `"vr_xK9mLPqRtN3vS8wF5hB2cQ"`
- `file` (FileSummary, required, nullable) — The file that was verified. `null` once the input file has been deleted.
- `status` (enum, required) — The status of the verify run: * `"PROCESSING"` - The document is still being checked * `"PROCESSED"` - Verification completed successfully; read `output` * `"FAILED"` - Verification failed (see `failureReason` for details) * `"CANCELLED"` - The run was cancelled before it completed
  - Allowed values: `PROCESSING`, `PROCESSED`, `FAILED`, `CANCELLED`
- `riskLevel` (enum, required, nullable) — The document-level risk level from the run's result. `null` until the run is `PROCESSED`, and `null` again once a zero-retention run's result has been purged.
  - Allowed values: `LOW`, `MEDIUM`, `HIGH`
- `failureReason` (string, required, nullable) — The reason for failure. Present when `status` is `"FAILED"`. See `VerifyRun` for the possible values.
- `failureMessage` (string, required, nullable) — A human-readable description of the failure. Present when `status` is `"FAILED"`.
- `metadata` (map from string to any, required, nullable) — Any metadata that was provided when creating the verify run.
- `metrics` (VerifyRunMetrics, required, nullable) — Present when `status` is `"PROCESSED"`.
- `config` (VerifyConfig, required) — The configuration that ran, with defaults applied: the `engine`, the concrete `engineVersion` that `"latest"` resolved to, and `advancedOptions.requireParsing` as it applied to this run.
- `usage` (RunUsage, required, nullable) — Usage credits consumed by this verify run.
- `source` (enum, required) — How the run was created.
  - Allowed values: `API`, `STUDIO`
- `sourceId` (string, required, nullable) — An identifier for the request that created the run. For API-created runs this is the request ID.
- `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"`

### VerifyRunMetrics

Metrics about the verification process.

- `processingTimeMs` (double, required) — Total processing time in milliseconds.
- `pageCount` (integer, required, nullable) — The number of pages in the document. `null` when the page count could not be determined, such as for some image inputs.

### VerifyConfig

Configuration for a verify run. Every field is optional on a request, and unknown keys are rejected with `400`. Runs echo the resolved configuration, with defaults applied, in `config`.

- `engine` (enum, optional) — The verification engine to use. Defaults to `"verify_agentic"`.
  - Allowed values: `verify_agentic`, `verify_light`
- `engineVersion` (string, optional) — The engine release to use. Pass a specific version (for example `"0.1.0"`) to pin your integration to that release, or `"latest"` (the default) to use the newest release. The response echoes the resolved version in `config.engineVersion`. Unsupported values return `400 INVALID_REQUEST`.
- `advancedOptions` (VerifyAdvancedOptions, optional) — Advanced options for a verify run. Every field is optional. Unknown keys are rejected with `400`.

### RunUsage

Usage credits consumed by a run. **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.
- `breakdown` (list of RunUsageBreakdownEntry, optional) — The chargeable resources that make up `totalCredits`, including this run itself when it has its own line item. For `workflow_run`, lists every contributing child run sorted by creation time (the workflow itself isn't chargeable and has no line item). **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.

### VerifyAdvancedOptions

Advanced options for a verify run. Every field is optional. Unknown keys are rejected with `400`.

- `requireParsing` (boolean, optional) — If `true`, this forces the verify run to parse the document if it has not already been parsed in Extend. This is for checks that require OCR, like detecting mismatches with the text layer. `verify_agentic` requires this to be `true`, and rejects `false` with `400`. `verify_light` parses only when this is `true`. Defaults to `false` for `verify_light` to reduce latency. In both cases, if the file has already been parsed in Extend with Verify's default parse settings and you reuse the `fileId` without zero data retention (ZDR), then the parsed results will be used here.

### RunUsageBreakdownEntry

One line item in a run's `usage.breakdown`. Each entry corresponds to a concrete chargeable resource that contributed credits to the parent operation. When `charges` is present, it itemizes the cost drivers behind this entry's `credits`.

- `object` (enum, required) — The public object type of the contributing resource. Mirrors the top-level `object` field on the corresponding endpoint so callers can fetch the underlying resource by id if they want more detail.
  - Allowed values: `extract_run`, `classify_run`, `split_run`, `parse_run`, `edit_run`, `form_detection_run`
- `id` (string, required) — The id of the contributing resource (e.g. `pr_3UZSj69pYZDKHFuuX57ic`).
- `credits` (double, required) — Credits charged to the contributing resource.
- `charges` (list of RunUsageBreakdownCharge, optional) — Itemized cost drivers that make up this entry's `credits`. When present, `sum(charges[].credits) === credits`. **Availability:** Present on runs persisted on or after June 10, 2026. Runs persisted before that date will omit this field.

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

### RunUsageBreakdownCharge

A single cost driver within a breakdown entry's credit total. The per-unit rate is `credits / quantity`. Certain charges, such as `agent_usage`, have a unit of `usd`

- `product` (string, required) — Identifier for the billable cost driver. Base charges use the processor and tier (e.g. `extraction_performance`, `extraction_light`, `parse_light`); add-ons use the feature code (e.g. `review_agent`, `large_array_max_context`, `extraction_schema_groups`, `priority_parsing`, `agentic_text_correction`, `advanced_excel_parsing`); `agent_usage` is an Operator overage for unusually high effort relative to document size.
- `unit` (enum, required) — The unit `quantity` is measured in. `page` for per-page charges, `cell` for advanced Excel parsing, `usd` for additional amounts billed such as Operator overages (`agent_usage`).
  - Allowed values: `page`, `cell`, `usd`
- `quantity` (double, required) — How many units this charge was billed for.
- `credits` (double, required) — Credits consumed by this charge.
- `pages` (list of integer, optional) — 1-indexed page numbers that incurred this charge. Present on usage-based add-ons that are only billed for the pages where they actually applied (e.g. `agentic_text_correction`, `agentic_table_correction`).

## Examples

**Response**

```json
{
  "object": "list",
  "data": [
    {
      "object": "verify_run",
      "id": "vr_xK9mLPqRtN3vS8wF5hB2cQ",
      "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": "PROCESSED",
      "riskLevel": "LOW",
      "failureReason": "string",
      "failureMessage": "string",
      "metadata": {},
      "metrics": {
        "processingTimeMs": 4210,
        "pageCount": 7
      },
      "config": {
        "engine": "verify_agentic",
        "engineVersion": "0.1.0",
        "advancedOptions": {
          "requireParsing": true
        }
      },
      "usage": {
        "credits": 9,
        "totalCredits": 15,
        "breakdown": [
          {
            "object": "parse_run",
            "id": "pr_3UZSj69pYZDKHFuuX57ic",
            "credits": 6,
            "charges": [
              {
                "product": "extraction_performance",
                "unit": "page",
                "quantity": 10,
                "credits": 30
              },
              {
                "product": "review_agent",
                "unit": "page",
                "quantity": 10,
                "credits": 10
              },
              {
                "product": "agentic_text_correction",
                "unit": "page",
                "quantity": 3,
                "credits": 3,
                "pages": [
                  2,
                  4,
                  7
                ]
              }
            ]
          }
        ]
      },
      "source": "API",
      "sourceId": "apireq_Xj8mK2pL9nR4vT7qY5wZ",
      "createdAt": "2024-03-21T16:45:00Z",
      "updatedAt": "2024-03-21T16:45:00Z"
    }
  ],
  "nextPageToken": "xK9mLPqRtN3vS8wF5hB2cQ==:zWvUxYjM4nKpL7aDgE9HbTcR2mAyX3/Q+CNkfBSw1dZ="
}
```