> This page is for version v2025-04-21.
> 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.

# Parse File Async

POST https://api.extend.ai/parse/async
Content-Type: application/json

Parse files **asynchronously** to get cleaned, chunked target content (e.g. markdown).

The Parse Async endpoint allows you to convert documents into structured, machine-readable formats with fine-grained control over the parsing process. This endpoint is ideal for extracting cleaned document content to be used as context for downstream processing, e.g. RAG pipelines, custom ingestion pipelines, embeddings classification, etc.

Parse files asynchronously and get a parser run ID that can be used to check status and retrieve results with the [Get Parser Run](https://docs.extend.ai/2025-04-21/developers/api-reference/parse-endpoints/get-parser-run) endpoint.

This is useful for:
* Large files that may take longer to process
* Avoiding timeout issues with synchronous parsing.

For more details, see the [Parse File guide](https://docs.extend.ai/2025-04-21/product/parsing/parse).


Reference: https://docs.extend.ai/2025-04-21/developers/api-reference/parse-endpoints/parse-file-async

## Authentication

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

## Request

### Headers

- `x-extend-api-version` ("2025-04-21", optional, default: 2025-04-21) — API version to use for the request. If you 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/2025-04-21/developers/api-versioning) for more details.

### Body (application/json)

This endpoint expects an object.

- `file` (ParseAsyncPostRequestBodyContentApplicationJsonSchemaFile, required) — A file object containing either a URL or a fileId.
- `config` (ParseConfig, optional) — Configuration options for the parsing process.

## Response

### 202

Successfully initiated parser run

- `object` (enum, required) — The type of object. Will always be `"parser_run_status"`.
  - Allowed values: `parser_run_status`
- `id` (string, required) — A unique identifier for the parser run. Will always start with `"parser_run_"` Example: `"parser_run_xK9mLPqRtN3vS8wF5hB2cQ"`
- `status` (enum, required) — The status of the parser run.
  - Allowed values: `PROCESSING`, `PROCESSED`, `FAILED`
- `failureReason` (string, optional) — The reason for failure if status is "FAILED".

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

### ParseAsyncPostRequestBodyContentApplicationJsonSchemaFile

A file object containing either a URL or a fileId.

- `fileName` (string, optional) — The name of the file. If not set, the file name is taken from the url.
- `fileUrl` (string, optional) — A URL to download the file. For production use cases, we recommend using presigned URLs with a 5-15 minute expiration time. One of `fileUrl` or `fileId` must be provided.
- `fileId` (string, optional) — If you already have an Extend file id (for instance from running a workflow or a previous [file upload](https://docs.extend.ai/2025-04-21/developers/api-reference/file-endpoints/upload-file)) then you can use that file id when running the parse endpoint so that it leverage any cached data that might be available. The file id will start with "file_". One of `fileUrl` or `fileId` must be provided. Example: `"file_xK9mLPqRtN3vS8wF5hB2cQ"`

### ParseConfig

Configuration options for the parsing process.

- `target` (enum, optional, default: markdown) — The target format for the parsed content. Supported values: * `markdown`: True markdown with logical reading order (headings, lists, tables, checkboxes). Best default for LLMs/RAG and enables section-based chunking. * `spatial`: Layout/position-preserving text that uses markdown elements for block types but is not strictly markdown due to whitespace/tabs used to maintain placement. Only page-based chunking is supported. Guidance: * Prefer `markdown` for most documents, multi-column reading order, and retrieval use cases * Prefer `spatial` for messy/scanned/handwritten or skewed documents, when you need near 1:1 layout fidelity, or for BOL-like logistics docs See “Markdown vs Spatial” in the Parse guide for details: /2025-04-21/developers/guides/parse#markdown-vs-spatial
  - Allowed values: `markdown`, `spatial`
- `chunkingStrategy` (ParseConfigChunkingStrategy, optional) — Strategy for dividing the document into chunks.
- `engine` (enum, optional, default: parse_performance) — The parsing engine to use. Supported values: * `parse_performance`: Full-featured parsing engine with highest accuracy (default) * `parse_light`: Lightweight parsing engine optimized for high-volume, cost-sensitive ingestion. Uses the new layout model with full layout support and the markdown target at lower cost and latency, but performs worse than `parse_performance` on lower-quality scans, harder handwriting, larger tables, non-Latin-based languages, and dense checkbox regions.
  - Allowed values: `parse_performance`, `parse_light`
- `blockOptions` (ParseConfigBlockOptions, optional) — Options for controlling how different block types are processed.
- `advancedOptions` (ParseConfigAdvancedOptions, optional)

### ParseConfigChunkingStrategy

Strategy for dividing the document into chunks.

- `type` (enum, optional, default: page) — The type of chunking strategy. Supported values: * `page`: Chunk document by pages. * `document`: Entire document is a single chunk. Essentially no chunking. * `section`: Split by logical sections. Not supported for target=spatial.
  - Allowed values: `page`, `document`, `section`
- `options` (ParseConfigChunkingStrategyOptions, optional) — Additional options for the chunking strategy.

### ParseConfigBlockOptions

Options for controlling how different block types are processed.

- `figures` (ParseConfigBlockOptionsFigures, optional) — Options for figure blocks.
- `tables` (ParseConfigBlockOptionsTables, optional) — Options for table blocks.
- `text` (ParseConfigBlockOptionsText, optional) — Options for text blocks.

### ParseConfigAdvancedOptions

- `pageRotationEnabled` (boolean, optional, default: true) — Whether to automatically detect and correct page rotation.
- `pageRanges` (list of PageRangesItems, optional) — Limit processing to the specified page ranges. See [Page Ranges](https://docs.extend.ai/2025-04-21/product/page-ranges).
- `excelParsingMode` (enum, optional) — Controls how Excel files are parsed. * `basic`: Fast, deterministic parsing. * `advanced`: Enable layout block detection for complex spreadsheets. This mode incurs additional credits when enabled. For `.xls` files, `basic` mode is always used.
  - Allowed values: `basic`, `advanced`
- `excelSkipHiddenContent` (boolean, optional, default: false) — Whether to exclude hidden rows, columns, and sheets when parsing Excel files.
- `excelUseRawCellValues` (boolean, optional, default: false) — Whether to return raw calculated cell values instead of locale-formatted values when parsing Excel files. Useful when downstream processing needs the underlying numeric or unformatted data.
- `excelSkipCalculation` (boolean, optional, default: true) — Whether to skip formula recalculation when opening Excel workbooks. Significantly improves parsing speed for formula-heavy spreadsheets. Disable if cell values depend on volatile functions like NOW() or TODAY().
- `excelIncludeCellMetadata` (boolean, optional, default: false) — Whether to include spreadsheet cell provenance when parsing Excel files in advanced mode. When enabled, table cell block details include source cell references and formulas, text or heading block details can include source ranges, and HTML table output includes `data-cell` and `data-formula` attributes.
- `excelIncludeCellFormatting` (boolean, optional, default: false) — Whether to include spreadsheet cell formatting when parsing Excel files in advanced mode. When enabled, table cell block details include structured formatting such as bold, italic, font color, and background color, and HTML table output preserves inline cell styles.
- `verticalGroupingThreshold` (double, optional, default: 1) — Multiplier for the Y-axis threshold used to determine if text blocks should be placed on the same line or not (0.1-5.0, default 1.0). Higher values group elements that are further apart vertically. Only applies when the spatial target is set.
- `returnOcr` (ParseConfigAdvancedOptionsReturnOcr, optional) — Options for returning raw OCR data in the response.
- `alwaysConvertToPdf` (boolean, optional, default: false) — Whether to convert supported file types (images, Word documents, PowerPoint, Excel, HTML) to PDF before parsing. This can improve parsing quality for some file types and ensures spatial output with bounding boxes.
- `agenticOcrEnabled` (boolean, optional, default: false, deprecated) — Whether to enable agentic OCR corrections using VLM-based review and correction of OCR errors for messy handwriting and poorly scanned text. Deprecated - use `blockOptions.text.agentic` or `blockOptions.tables.agentic` instead for more granular control.

### ParseConfigChunkingStrategyOptions

Additional options for the chunking strategy.

- `minCharacters` (integer, optional) — Specify a minimum number of characters per chunk.
- `maxCharacters` (integer, optional) — Specify a maximum number of characters per chunk.

### ParseConfigBlockOptionsFigures

Options for figure blocks.

- `enabled` (boolean, optional, default: true) — Whether to include figures in the output.
- `figureImageClippingEnabled` (boolean, optional, default: true) — Whether to clip and extract images from figures.

### ParseConfigBlockOptionsTables

Options for table blocks.

- `targetFormat` (enum, optional, default: markdown) — The target format for the table blocks. Supported values: * `markdown`: Convert table to Markdown format * `html`: Convert table to HTML format
  - Allowed values: `markdown`, `html`
- `tableHeaderContinuationEnabled` (boolean, optional, default: false) — Whether to automatically copy table headers to headerless tables on subsequent pages when they have matching column counts. Useful for multi-page tables.
- `cellBlocksEnabled` (boolean, optional, default: false) — Whether to include individual table cell blocks in the output. When enabled, each cell in a table will be represented as a separate block with its own bounding box and content and will be `children` of the table block.
- `agentic` (ParseConfigBlockOptionsTablesAgentic, optional) — Options for agentic table processing using VLM-based review and correction. Enabling this incurs additional credits on pages where agentic table correction is triggered.
- `enabled` (boolean, optional, default: true, deprecated) — This option is deprecated and will have no effect. It will be removed in the next API version.

### ParseConfigBlockOptionsText

Options for text blocks.

- `signatureDetectionEnabled` (boolean, optional, default: true) — Whether an additional vision model will be utilized for advanced signature detection. Recommended for most use cases, but should be disabled if signature detection is not necessary and latency is a concern.
- `agentic` (ParseConfigBlockOptionsTextAgentic, optional) — Options for agentic text processing using VLM-based review and correction. Enabling this incurs additional credits on pages where agentic text correction is triggered.

### PageRangesItems

- `start` (integer, optional) — The start page of the range.
- `end` (integer, optional, default: 750) — The end page of the range.

### ParseConfigAdvancedOptionsReturnOcr

Options for returning raw OCR data in the response.

- `words` (boolean, optional, default: false) — Whether to include word-level OCR data in the response, including word bounding boxes and confidence scores. This meaningfully impacts the response size, consider using the signed url return format.

### ParseConfigBlockOptionsTablesAgentic

Options for agentic table processing using VLM-based review and correction. Enabling this incurs additional credits on pages where agentic table correction is triggered.

- `enabled` (boolean, optional, default: false) — Whether to enable agentic table processing.
- `customInstructions` (string, optional) — Custom instructions to guide the agentic table processing.

### ParseConfigBlockOptionsTextAgentic

Options for agentic text processing using VLM-based review and correction. Enabling this incurs additional credits on pages where agentic text correction is triggered.

- `enabled` (boolean, optional, default: false) — Whether to enable agentic text processing for OCR corrections.
- `customInstructions` (string, optional) — Custom instructions to guide the agentic text processing.

## Examples

**Request**

```json
{
  "file": {}
}
```

**Response**

```json
{
  "object": "parser_run_status",
  "id": "parser_run_xK9mLPqRtN3vS8wF5hB2cQ",
  "status": "PROCESSING",
  "failureReason": "string"
}
```