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

# Get Parser Run

GET https://api.extend.ai/parser_runs/{id}

Retrieve the status and results of a parser run.

Use this endpoint to get results for a parser run that has already completed, or to check on the status of an asynchronous parser run initiated via the [Parse File Asynchronously](https://docs.extend.ai/2025-04-21/developers/api-reference/parse-endpoints/parse-file-async) endpoint.

If parsing is still in progress, you'll receive a response with just the status. Once complete, you'll receive the full parsed content in the response.


Reference: https://docs.extend.ai/2025-04-21/developers/api-reference/parse-endpoints/get-parser-run

## Authentication

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

## Request

### Path parameters

- `id` (string, required) — The unique identifier for the parser run. Example: `"parser_run_xK9mLPqRtN3vS8wF5hB2cQ"`

### Query parameters

- `responseType` (enum, optional) — Controls the format of the response chunks. Defaults to `json` if not specified. * `json` - Returns chunks with inline content * `url` - Returns chunks with presigned URLs to content instead of inline data
  - Allowed values: `json`, `url`

### 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.
- `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/2025-04-21/developers/authentication) for details on API key scopes.

## Response

### 200

Successfully retrieved parser run

- `success` (boolean, required)
- `parserRun` (ParserRunsIdGetResponsesContentApplicationJsonSchemaParserRun, required)
- `warning` (string, optional) — Warning message about missing API version header if applicable

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

### 404 Not Found Error

Not Found

- `success` (boolean, optional)
- `error` (string, optional) — Error message

## Types

### ParserRunsIdGetResponsesContentApplicationJsonSchemaParserRun

- ParserRunStatus: ParserRunStatus
- ParserRun: ParserRun

### ParserRunStatus

Minimal parser run status object without parser results.

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

### ParserRun

Full parser run object with complete parsing results

- `object` (enum, required) — The type of object. Will always be `"parser_run"`.
  - Allowed values: `parser_run`
- `id` (string, required) — A unique identifier for the parser run. Will always start with `"parser_run_"` Example: `"parser_run_xK9mLPqRtN3vS8wF5hB2cQ"`
- `fileId` (string, required) — The identifier of the file that was parsed. This can be used as a parameter to other Extend endpoints, such as processor runs.
- `chunks` (list of Chunk, required) — An array of chunks that were parsed from the file.
- `status` (enum, required) — The status of the parser run: * `"PROCESSED"` - The file was successfully processed * `"FAILED"` - The processing failed (see failureReason for details)
  - Allowed values: `PROCESSED`, `FAILED`
- `metrics` (ParserRunMetrics, required) — Metrics about the parsing process.
- `config` (ParseConfig, required) — The configuration used for the parsing process, including any default values that were applied.
- `ocr` (ParserRunOcr, optional) — Raw OCR data from the parsing process. Words and lines are independently enabled with `returnOcr.words` and `returnOcr.lines`; either array may be omitted.
- `failureReason` (string, optional) — The reason for failure if status is "FAILED".
- `usage` (ParserRunCredits, optional) — These are usage credits for parser runs. This field will not be returned for parser runs created before October 7, 2025, or for customers on legacy billing systems. For more details on how credits work, see our [Credits Guide](https://docs.extend.ai/general/how-credits-work).

### Chunk

- `object` (string, required) — The type of object. In this case, it will always be `"chunk"`.
- `type` (enum, required) — The type of chunk.
  - Allowed values: `page`, `document`, `section`
- `content` (string, required) — The parsed content of the chunk.
- `metadata` (ChunkMetadata, required) — Metadata about the chunk.
- `blocks` (list of Block, required) — An array of block objects that make up the chunk. A Block represents a distinct content element within a document, such as a paragraph of text, a heading, a table, or a figure. Blocks are the fundamental units that make up chunks in parsed documents.

### ParserRunMetrics

Metrics about the parsing process.

- `processingTimeMs` (double, required) — The time taken to process the document in milliseconds.
- `pageCount` (double, required) — The number of pages in the document.

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

### ParserRunOcr

Raw OCR data from the parsing process. Words and lines are independently enabled with `returnOcr.words` and `returnOcr.lines`; either array may be omitted.

- `words` (list of ParserRunOcrWordsItems, optional) — An array of individual words detected by OCR.
- `lines` (list of ParserRunOcrLinesItems, optional) — Text lines detected by OCR. Only included when `config.advancedOptions.returnOcr.lines` is true and line data is available; enabling words does not enable lines.

### ParserRunCredits

These are usage credits for parser runs. This field will not be returned for parser runs created before October 7, 2025, or for 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 number of credits consumed for parsing in this parser run.

### ChunkMetadata

Metadata about the chunk.

- `pageRange` (ChunkMetadataPageRange, required) — The page range this chunk covers. Often will just be a partial page, in which cases `start` and `end` will be the same.

### Block

- `object` (string, required) — The type of object. In this case, it will always be `"block"`.
- `id` (string, required) — A unique identifier for the block, deterministically generated as a hash of the block content.
- `type` (enum, required) — The type of block: * `"text"` - Regular text content * `"heading"` - Section or document headings * `"section_heading"` - Subsection headings * `"table"` - Tabular data with rows and columns * `"table_head"` - Table header cells * `"table_cell"` - Table body cells * `"figure"` - Images, charts, diagrams, or logos * `"key_value"` - Key-value pair content (e.g., form field labels and values) * `"header"` - Page header content * `"footer"` - Page footer content
  - Allowed values: `text`, `heading`, `section_heading`, `table`, `figure`, `table_head`, `table_cell`, `key_value`, `header`, `footer`
- `content` (string, required) — The textual content of the block formatted based on the target format.
- `details` (BlockDetails, required) — Additional details specific to the block type. The schema depends on the block type.
- `metadata` (BlockMetadata, required) — Metadata about the block.
- `polygon` (list of BlockPolygonItems, required) — An array of points defining the polygon that bounds the block.
- `boundingBox` (BlockBoundingBox, required) — A simplified bounding box for the block.
- `parentBlockId` (string, optional) — The ID of the parent block. For example, for a table cell block, this would be the ID of the parent table block. Only set if this is a child block.
- `children` (list of Block, optional) — An array of child blocks. For example, a table block may contain table cell blocks as children when `cellBlocksEnabled` is set to true.

### 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. Words and lines are independent opt-ins and both default to false.
- `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.

### ParserRunOcrWordsItems

- `content` (string, required) — The text content of the word.
- `boundingBox` (ParserRunOcrWordsItemsBoundingBox, required) — The bounding box coordinates of the word.
- `confidence` (double, required) — The confidence score of the OCR detection for this word, between 0 and 1.
- `pageNumber` (double, required) — The page number where the word was detected.

### ParserRunOcrLinesItems

- `content` (string, required) — The text content of the line.
- `boundingBox` (ParserRunOcrLinesItemsBoundingBox, required) — The bounding box of the line in the same page coordinate space as blocks, measured from the top-left corner.
- `pageNumber` (double, required) — The page number where the line was detected.
- `confidence` (double, optional) — The OCR confidence score for this line, between 0 and 1. Omitted when unavailable.
- `blockId` (string, optional) — The `id` of the block this line was assigned to, based on bounding-box overlap. Omitted when no block was assigned.

### ChunkMetadataPageRange

The page range this chunk covers. Often will just be a partial page, in which cases `start` and `end` will be the same.

- `start` (integer, required) — The starting page number (inclusive).
- `end` (integer, required) — The ending page number (inclusive).

### BlockDetails

Additional details specific to the block type. The schema depends on the block type.

- TextDetails: TextDetails
- TableDetails: TableDetails
- TableCellDetails: TableCellDetails
- FigureDetails: FigureDetails
- KeyValueDetails: KeyValueDetails
- EmptyBlockDetails: EmptyBlockDetails

### BlockMetadata

Metadata about the block.

- `page` (BlockMetadataPage, optional) — Information about the page this block appears on.
- `sheet` (BlockMetadataSheet, optional) — Spreadsheet sheet metadata. Present for blocks parsed from spreadsheet files, such as Excel workbooks.

### BlockPolygonItems

- `x` (double, required)
- `y` (double, required)

### BlockBoundingBox

A simplified bounding box for the block.

- `left` (double, required, nullable)
- `right` (double, required, nullable)
- `top` (double, required, nullable)
- `bottom` (double, required, nullable)

### 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 and lines are independent opt-ins and both default to false.

- `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.
- `lines` (boolean, optional, default: false) — Whether to include line-level OCR data at `ocr.lines`, including bounding boxes and confidence scores when available. Does not enable word-level OCR output.

### ParserRunOcrWordsItemsBoundingBox

The bounding box coordinates of the word.

- `left` (double, required) — The left coordinate of the bounding box.
- `right` (double, required) — The right coordinate of the bounding box.
- `top` (double, required) — The top coordinate of the bounding box.
- `bottom` (double, required) — The bottom coordinate of the bounding box.

### ParserRunOcrLinesItemsBoundingBox

The bounding box of the line in the same page coordinate space as blocks, measured from the top-left corner.

- `left` (double, required) — The left coordinate of the bounding box.
- `right` (double, required) — The right coordinate of the bounding box.
- `top` (double, required) — The top coordinate of the bounding box.
- `bottom` (double, required) — The bottom coordinate of the bounding box.

### TextDetails

Details for text and heading blocks

- `type` (enum, required) — Indicates this is a text details object
  - Allowed values: `text_details`
- `cellReference` (string, optional) — Source spreadsheet cell or range in A1 notation for Excel-derived text or heading blocks. Only set when `advancedOptions.excelIncludeCellMetadata` is enabled.

### TableDetails

Details for table blocks

- `type` (enum, required) — Indicates this is a table details object
  - Allowed values: `table_details`
- `rowCount` (integer, required) — The number of rows in the table
- `columnCount` (integer, required) — The number of columns in the table

### TableCellDetails

Details for table cell blocks

- `type` (enum, required) — Indicates this is a table cell details object
  - Allowed values: `table_cell_details`
- `rowIndex` (integer, required)
- `columnIndex` (integer, required)
- `cellReference` (string, optional) — Source spreadsheet cell or range in A1 notation, such as `B2` or `A1:C1` for a merged cell. Only set for Excel table cells when `advancedOptions.excelIncludeCellMetadata` is enabled.
- `formula` (string, optional) — Source spreadsheet formula text with a leading `=`, when the cell has a formula. Only set for Excel table cells when `advancedOptions.excelIncludeCellMetadata` is enabled.
- `formatting` (CellFormatting, optional) — Structured spreadsheet cell formatting. Only set when `advancedOptions.excelIncludeCellFormatting` is enabled and formatting is present.

### FigureDetails

Details for figure blocks

- `type` (enum, required) — Indicates this is a figure details object
  - Allowed values: `figure_details`
- `imageUrl` (string, optional) — URL to the clipped/segmented figure image. Only set if the option `figureImageClippingEnabled` in the input is `true`, which it is by default.
- `figureType` (enum, optional) — The refined type of figure - only set when figure classification and summarization is enabled. Possible values: * `image`: A photographic image * `chart`: A data chart or graph * `diagram`: A schematic or diagram * `logo`: A company or brand logo * `other`: Any other type of figure
  - Allowed values: `other`, `chart`, `image`, `diagram`, `logo`

### KeyValueDetails

Details for key-value pair blocks

- `type` (enum, required) — Indicates this is a key-value details object
  - Allowed values: `key_value_details`

### EmptyBlockDetails

An empty object

### BlockMetadataPage

Information about the page this block appears on.

- `number` (integer, required) — The page number where this block appears.
- `width` (double, optional) — The width of the page in points.
- `height` (double, optional) — The height of the page in points.

### BlockMetadataSheet

Spreadsheet sheet metadata. Present for blocks parsed from spreadsheet files, such as Excel workbooks.

- `index` (integer, required) — The zero-based index of the sheet in the original workbook.
- `name` (string, required) — The name of the sheet in the original workbook.

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

### CellFormatting

Structured formatting for an Excel table cell

- `bold` (boolean, optional) — Whether the cell text is bold.
- `italic` (boolean, optional) — Whether the cell text is italic.
- `fontColor` (string, optional) — Cell font color as a hex string.
- `backgroundColor` (string, optional) — Cell background color as a hex string.

## Examples

**Response**

```json
{
  "success": true,
  "parserRun": {
    "object": "parser_run_status",
    "id": "parser_run_xK9mLPqRtN3vS8wF5hB2cQ",
    "status": "PROCESSING",
    "failureReason": "string"
  },
  "warning": "string"
}
```