> 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. # Cancel Parse Run POST https://api.extend.ai/parse_runs/{id}/cancel Cancel an in-progress parse run. Note: Only parse runs with a status of `"PROCESSING"` can be cancelled. Parse runs that have already completed, failed, or been cancelled cannot be cancelled again. Reference: https://docs.extend.ai/api-reference/endpoints/parse/cancel-parse-run ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, 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 ### Path parameters - `id` (string, required) — The ID of the parse run to cancel. Example: `"pr_xK9mLPqRtN3vS8wF5hB2cQ"` ### 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 Parse run cancelled successfully - `object` (enum, required) — The type of object. Will always be `"parse_run"`. - Allowed values: `parse_run` - `id` (string, required) — A unique identifier for the parse run. Example: `"pr_xK9mLPqRtN3vS8wF5hB2cQ"` - `file` (FileSummary, required, nullable) — The file that was parsed. This file can be used as a parameter for other Extend endpoints, such as `POST /workflow_runs`. May be `null` for batch parse runs where file ingestion failed. - `status` (enum, required) — The status of the parse run: * `"PENDING"` - The run has been created and is waiting to be processed. Only applies to runs created via `POST /parse_runs/batch`. * `"PROCESSING"` - The file is still being processed * `"PROCESSED"` - The file was successfully processed * `"FAILED"` - The processing failed (see `failureReason` for details) - Allowed values: `PENDING`, `PROCESSING`, `PROCESSED`, `FAILED` - `failureReason` (string, required, nullable) — The reason for failure. **Availability:** Present when `status` is `"FAILED"`. Possible values include: * `UNABLE_TO_DOWNLOAD_FILE` - The file could not be downloaded from the provided URL * `FILE_TYPE_NOT_SUPPORTED` - The file type is not supported for parsing * `FILE_SIZE_TOO_LARGE` - The file exceeds the maximum allowed size * `CORRUPT_FILE` - The file appears to be corrupted or malformed * `OCR_ERROR` - An error occurred during optical character recognition * `PASSWORD_PROTECTED_FILE` - The file is password protected and cannot be processed * `FAILED_TO_CONVERT_TO_PDF` - The file could not be converted to PDF for processing * `FAILED_TO_CONVERT_TO_JPEG` - The file could not be converted to JPEG for processing * `FAILED_TO_GENERATE_TARGET_FORMAT` - The output could not be generated in the requested format * `CHUNKING_ERROR` - An error occurred while chunking the document * `INTERNAL_ERROR` - An unexpected internal error occurred * `INVALID_CONFIG_OPTIONS` - The provided configuration options are invalid * `OUT_OF_CREDITS` - Insufficient credits to process the file **Note:** Additional failure reasons may be added in the future. Your integration should handle unknown values gracefully. - `failureMessage` (string, required, nullable) — A human-readable description of the failure. **Availability:** Present when `status` is `"FAILED"`. - `metadata` (map from string to any, required, nullable) — Any metadata that was provided when creating the parse run. **Availability:** Present when metadata was provided during creation. - `output` (ParseRunOutput, required, nullable) — The parse run output. **Availability:** Present when `status` is `"PROCESSED"` and the request was made without the `responseType=url` query parameter. Contains the parsed chunks. - `outputUrl` (string, required, nullable) — A presigned URL to download the parse run output as a JSON file. The object shape is the same as the `output` field. Expires after 15 minutes. **Availability:** Present when `status` is `"PROCESSED"` and the request was made with `responseType=url` query parameter. - `metrics` (ParseRunMetrics, required, nullable) — Metrics about the parsing process. **Availability:** Present when `status` is `"PROCESSED"`. - `config` (ParseConfig, required) — The configuration used for the parsing process, including any default values that were applied. - `usage` (RunUsage, required, nullable) — Usage credits consumed by this parse run. **Availability:** Present when `status` is `"PROCESSED"`, the run was created after October 7, 2025, and the customer is on the current billing system. - `batchId` (string, optional, nullable) — The ID of the batch this run belongs to, if created via `POST /parse_runs/batch`. **Availability:** Present when the run was submitted as part of a batch. Example: `"bpar_Xj8mK2pL9nR4vT7qY5wZ"` ## 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 ### 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"` ### ParseRunOutput The parse run output. **Availability:** Present when `status` is `"PROCESSED"` and the request was made without the `responseType=url` query parameter. Contains the parsed chunks. - `chunks` (list of Chunk, required) — An array of chunks that were parsed from the file. - `ocr` (ParseRunOutputOcr, optional) — Raw OCR data from the parsing process. Only included when `returnOcr` is configured in the parse config's advanced options. - `metadata` (ParseRunOutputMetadata, optional, nullable) — Rotation, dimension, and file-type metadata about the parse output. `null` for parse runs that completed before this field was introduced. ### ParseRunMetrics Metrics about the parsing process. **Availability:** Present when `status` is `"PROCESSED"`. - `processingTimeMs` (double, required) — The time taken to process the document in milliseconds. - `pageCount` (double, required) — The number of pages from the document that were parsed. For PDF and image files, this is the actual page count. For spreadsheet files (Excel, CSV), this is an estimated page count based on content volume (~1000 tokens per page). ### ParseConfig Configuration options for the parsing process. Defaults depend on the selected parser engine and version. - `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](https://docs.extend.ai/2026-02-09/parsing/configuration#target-format) for details. - 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. * `parse_auto`: Adaptive parsing that classifies difficulty and routes work per page — simple pages are parsed with the parse_light model pipeline while complex pages get performance-level model treatment. Billed per page by complexity. - Allowed values: `parse_performance`, `parse_light`, `parse_auto` - `engineVersion` (string, optional, default: latest) — Pin a specific parser engine version for reproducibility. When set to `latest`, the most recent stable version of the selected engine is used. - `blockOptions` (ParseConfigBlockOptions, optional) — Options for controlling how different block types are processed. - `advancedOptions` (ParseConfigAdvancedOptions, optional) ### 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. ### Chunk - `object` (enum, required) — The type of object. In this case, it will always be `"chunk"`. - Allowed values: `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. ### ParseRunOutputOcr Raw OCR data from the parsing process. Only included when `returnOcr` is configured in the parse config's advanced options. - `words` (list of ParseRunOutputOcrWordsItems, optional) — An array of individual words detected by OCR. ### ParseRunOutputMetadata Rotation, dimension, and file-type metadata about the parse output. `null` for parse runs that completed before this field was introduced. - `originalMimeType` (string, optional, nullable) — The file's media type before any format conversion. - `finalMimeType` (string, optional, nullable) — The file's media type after any format conversion. - `pages` (list of ParseRunOutputMetadataPagesItems, optional, nullable) — Per-page rotation and original-dimension info. Set when file is a PDF or was converted to PDF. ### 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. - `keyValue` (ParseConfigBlockOptionsKeyValue, optional) — Options for key-value pair blocks. - `barcodes` (ParseConfigBlockOptionsBarcodes, optional) — Options for barcode blocks. - `formulas` (ParseConfigBlockOptionsFormulas, optional) — Options for formula 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/2026-02-09/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. - `enrichmentFormat` (enum, optional, default: xml) — The format used for enrichment annotations in the output. * `xml`: Use XML-style tags for enrichment annotations, e.g. 1 or 1234567890 * `bracket`: Use bracket-style notation for enrichment annotations, e.g. \[page\_number: 1] or \[barcode: 1234567890] - Allowed values: `xml`, `bracket` - `imageConversionQuality` (enum, optional, default: medium) — Controls the quality level when converting images or documents to PDF for parsing. * `high`: Maximum quality, can add some latency for large/dense documents * `medium`: Balanced quality and speed * `low`: Lower quality, smaller file sizes, faster processing - Allowed values: `high`, `medium`, `low` - `formattingDetection` (list of ParseConfigAdvancedOptionsFormattingDetectionItems, optional) — Enable detection of formatting-based annotations in the document. Currently supports change tracking detection. When enabled, detected changes are represented inline within the `content` field of applicable blocks using standard HTML change-tracking elements: [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ins) for insertions and [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del) for deletions, grouped inside a `` wrapper. Affected block types: `text`, `heading`, `section_heading`, `header`, `footer`. **Note:** Requires `engine: "parse_performance"` with `engineVersion >= "2.0.0"`. ### 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. ### 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. - `minOcrConfidence` (double, optional, nullable) — Lowest per-word OCR confidence across words in this chunk, or `null` when word-level confidence is unavailable. - `avgOcrConfidence` (double, optional, nullable) — Average per-word OCR confidence across words in this chunk, or `null` when word-level confidence is unavailable. ### Block - `object` (enum, required) — The type of object. In this case, it will always be `"block"`. - Allowed values: `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 * `"figure"` - Images, charts, diagrams, or logos * `"table_head"` - Table header cells * `"table_cell"` - Table body cells * `"key_value"` - Key-value pairs (e.g., form regions, key-val groups, etc) * `"page_number"` - Page number indicators * `"barcode"` - Barcodes and QR codes * `"formula"` - Mathematical formulas and equations * `"header"` - Page headers * `"footer"` - Page footers - Allowed values: `text`, `heading`, `section_heading`, `table`, `figure`, `table_head`, `table_cell`, `key_value`, `page_number`, `barcode`, `formula`, `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` (BoundingBox, 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. ### ParseRunOutputOcrWordsItems - `content` (string, required) — The text content of the word. - `boundingBox` (BoundingBox, 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. - `blockId` (string, optional) — The `id` of the block (see the `Block` schema) this word was assigned to, based on bounding-box overlap. Omitted when the word doesn't fall within any block's bounding box. - `rotation` (double, optional, nullable) — Clockwise degrees the word is rotated from upright, as a whole number in `[0, 360)`. `null` when the orientation could not be calculated for the word. **Availability:** Present on parse runs created on or after October 6, 2026. ### ParseRunOutputMetadataPagesItems - `number` (integer, required) — The page number this entry describes. - `rotationApplied` (integer, required, nullable) — Degrees Extend rotated the page clockwise to make it upright. `0` if rotation detection ran and the page was already upright; `null` if rotation detection was disabled for this run. - `originalPageWidth` (double, required) — The file's true page width, independent of rendering resolution. - `originalPageHeight` (double, required) — The file's true page height, independent of rendering resolution. - `dpi` (double, required) — The DPI that `boundingBox`/`polygon` coordinates on this page are scaled to. Multiply `originalPageWidth`/`originalPageHeight` by `dpi / 72` to convert them into that same coordinate space. ### ParseConfigChunkingStrategyOptions Additional options for the chunking strategy. - `minCharacters` (integer, optional, default: 500) — Specify a minimum number of characters per chunk. - `maxCharacters` (integer, optional, default: 10000) — 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. - `advancedChartExtractionEnabled` (boolean, optional, default: false) — Whether to enable advanced chart extraction using vision models for improved data extraction from charts. - `customInstructions` (string, optional) — Custom instructions injected into the vision model prompt used to analyze and summarize figures. Use to steer figure descriptions toward your use case (e.g. domain terminology, details to always capture). Requires `enabled: true`. Available on `parse_performance` >= `2.0.0` and `parse_light` >= `1.0.0`. ### ParseConfigBlockOptionsTables Options for table blocks. - `targetFormat` (enum, optional, default: html) — 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. Only supported on `parse_performance` engineVersion `1.0.1`. - `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: false) — 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. ### ParseConfigBlockOptionsKeyValue Options for key-value pair blocks. - `blankFieldFormattingEnabled` (boolean, optional, default: false) — Whether to preserve blank field formatting for key-value pairs with empty values. ### ParseConfigBlockOptionsBarcodes Options for barcode blocks. - `imageClippingEnabled` (boolean, optional, default: false) — Whether to clip and extract images of barcodes. When enabled, barcode images will be available in the `imageUrl` field of BarcodeDetails. - `readingEnabled` (boolean, optional, default: false) — Whether to decode and read barcode values. When enabled, decoded values will be available in the `decodedValue` field of BarcodeDetails. ### ParseConfigBlockOptionsFormulas Options for formula blocks. - `enabled` (boolean, optional, default: false) — Whether to enable formula detection and parsing. When enabled, mathematical formulas and equations are detected and their LaTeX representations are included in the output. When disabled, formulas will be detected as text blocks and may not be accurately parsed. ### PageRangesItems - `start` (integer, required) — The start page of the range. - `end` (integer, required, 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. ### ParseConfigAdvancedOptionsFormattingDetectionItems - `type` (enum, required) — The type of formatting detection to enable. * `"change_tracking"` — Detect tracked changes (insertions, deletions, substitutions) indicated by strikethroughs, colored text, or underlines in the source document. - Allowed values: `change_tracking` ### 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`). ### 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. ### 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. - `minOcrConfidence` (double, optional, nullable) — Lowest per-word OCR confidence across words in this block, or `null` when word-level confidence is unavailable. - `avgOcrConfidence` (double, optional, nullable) — Average per-word OCR confidence across words in this block, or `null` when word-level confidence is unavailable. ### BlockPolygonItems - `x` (double, required) - `y` (double, required) ### BoundingBox A bounding box defined by its edges. - `left` (double, required, nullable) — The left coordinate of the bounding box. - `top` (double, required, nullable) — The top coordinate of the bounding box. - `right` (double, required, nullable) — The right coordinate of the bounding box. - `bottom` (double, required, nullable) — The bottom coordinate of the bounding box. ### 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. ### 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` ### BarcodeDetails Details for barcode blocks - `type` (enum, required) — Indicates this is a barcode details object - Allowed values: `barcode_details` - `imageUrl` (string, optional) — URL to the clipped/segmented barcode image. Only set if the option `imageClippingEnabled` in blockOptions.barcodes is `true`. - `decodedValue` (string, optional) — The decoded value of the barcode or QR code. Only set if the option `readingEnabled` in blockOptions.barcodes is `true`. - `format` (string, optional) — The format of the barcode (e.g., "QRCode", "Code128", "DataMatrix", "EAN13"). ### FormulaDetails Details for formula blocks - `type` (enum, required) — Indicates this is a formula details object - Allowed values: `formula_details` - `latex` (string, optional) — The LaTeX representation of the detected formula. ### 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. ### 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 { "object": "parse_run", "id": "pr_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": "PENDING", "failureReason": "FILE_TYPE_NOT_SUPPORTED", "failureMessage": "File type not supported for parsing.", "metadata": {}, "output": { "chunks": [ { "object": "chunk", "type": "page", "content": "This is the content of the chunk.", "metadata": { "pageRange": { "start": 1, "end": 1 }, "minOcrConfidence": 1.1, "avgOcrConfidence": 1.1 }, "blocks": [ { "object": "block", "id": "string", "type": "text", "content": "string", "details": {}, "metadata": { "page": { "number": 1, "width": 1.1, "height": 1.1 }, "sheet": { "index": 0, "name": "Sheet1" }, "minOcrConfidence": 1.1, "avgOcrConfidence": 1.1 }, "polygon": [ { "x": 10, "y": 20 } ], "boundingBox": { "left": 10, "top": 10, "right": 20, "bottom": 20 }, "parentBlockId": "string", "children": [ null ] } ] } ], "ocr": { "words": [ { "content": "string", "boundingBox": { "left": 10, "top": 10, "right": 20, "bottom": 20 }, "confidence": 1.1, "pageNumber": 1.1, "blockId": "string", "rotation": 1.1 } ] }, "metadata": { "originalMimeType": "string", "finalMimeType": "string", "pages": [ { "number": 1, "rotationApplied": 1, "originalPageWidth": 1.1, "originalPageHeight": 1.1, "dpi": 1.1 } ] } }, "outputUrl": "https://...", "metrics": { "processingTimeMs": 1234, "pageCount": 5 }, "config": { "target": "markdown", "chunkingStrategy": { "type": "page", "options": { "minCharacters": 500, "maxCharacters": 10000 } }, "engine": "parse_performance", "engineVersion": "latest", "blockOptions": { "figures": { "enabled": true, "figureImageClippingEnabled": true, "advancedChartExtractionEnabled": false, "customInstructions": "string" }, "tables": { "targetFormat": "html", "tableHeaderContinuationEnabled": false, "cellBlocksEnabled": false, "agentic": { "enabled": false, "customInstructions": "string" }, "enabled": true }, "text": { "signatureDetectionEnabled": false, "agentic": { "enabled": false, "customInstructions": "string" } }, "keyValue": { "blankFieldFormattingEnabled": false }, "barcodes": { "imageClippingEnabled": false, "readingEnabled": false }, "formulas": { "enabled": false } }, "advancedOptions": { "pageRotationEnabled": true, "pageRanges": [ { "start": 1, "end": 10 }, { "start": 20, "end": 30 } ], "excelParsingMode": "basic", "excelSkipHiddenContent": false, "excelUseRawCellValues": false, "excelSkipCalculation": true, "excelIncludeCellMetadata": false, "excelIncludeCellFormatting": false, "verticalGroupingThreshold": 1, "returnOcr": { "words": false }, "alwaysConvertToPdf": false, "enrichmentFormat": "xml", "imageConversionQuality": "medium", "formattingDetection": [ { "type": "change_tracking" } ] } }, "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 ] } ] } ] }, "batchId": "bpar_Xj8mK2pL9nR4vT7qY5wZ" } ```