Parse File | Extend Documentation

{
  "object": "parser_run",
  "id": "parser_run_xK9mLPqRtN3vS8wF5hB2cQ",
  "fileId": "file_Zk9mNP12Qw4yTv8BdR3H",
  "chunks": [
    {
      "object": "chunk",
      "type": "page",
      "content": "This is the content of the chunk.",
      "metadata": {
        "pageRange": {
          "start": 1,
          "end": 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"
            }
          },
          "polygon": [
            {
              "x": 10,
              "y": 20
            }
          ],
          "boundingBox": {
            "left": 10,
            "right": 20,
            "top": 10,
            "bottom": 20
          },
          "parentBlockId": "string",
          "children": [
            null
          ]
        }
      ]
    }
  ],
  "status": "PROCESSED",
  "metrics": {
    "processingTimeMs": 1.1,
    "pageCount": 1.1
  },
  "config": {
    "target": "markdown",
    "chunkingStrategy": {
      "type": "page",
      "options": {
        "minCharacters": 100,
        "maxCharacters": 1000
      }
    },
    "engine": "parse_performance",
    "blockOptions": {
      "figures": {
        "enabled": true,
        "figureImageClippingEnabled": true
      },
      "tables": {
        "targetFormat": "markdown",
        "tableHeaderContinuationEnabled": false,
        "cellBlocksEnabled": false,
        "agentic": {
          "enabled": false,
          "customInstructions": "string"
        },
        "enabled": true
      },
      "text": {
        "signatureDetectionEnabled": true,
        "agentic": {
          "enabled": false,
          "customInstructions": "string"
        }
      }
    },
    "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,
        "lines": false
      },
      "alwaysConvertToPdf": false,
      "agenticOcrEnabled": false
    }
  },
  "ocr": {
    "words": [
      {
        "content": "string",
        "boundingBox": {
          "left": 1.1,
          "right": 1.1,
          "top": 1.1,
          "bottom": 1.1
        },
        "confidence": 1.1,
        "pageNumber": 1.1
      }
    ],
    "lines": [
      {
        "content": "string",
        "boundingBox": {
          "left": 1.1,
          "right": 1.1,
          "top": 1.1,
          "bottom": 1.1
        },
        "pageNumber": 1.1,
        "confidence": 1.1,
        "blockId": "string"
      }
    ]
  },
  "failureReason": "string",
  "usage": {
    "credits": 10
  }
}

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

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

For more details, see the Parse File guide.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Query parameters

responseTypeenumOptional

Controls the format of the response chunks. Defaults to json if not specified.

json - Returns parsed outputs in the response body
url - Return a presigned URL to the parsed content in the response body

Allowed values:

Request

This endpoint expects an object.

fileobjectRequired

A file object containing either a URL or a fileId.

configobjectOptional

Configuration options for the parsing process.

Response

Successfully parsed file

objectenum

The type of object. Will always be "parser_run".

Allowed values:

idstring

A unique identifier for the parser run. Will always start with "parser_run_"

Example: "parser_run_xK9mLPqRtN3vS8wF5hB2cQ"

fileIdstring

The identifier of the file that was parsed. This can be used as a parameter to other Extend endpoints, such as processor runs.

chunkslist of objects

An array of chunks that were parsed from the file.

statusenum

The status of the parser run:

"PROCESSED" - The file was successfully processed
"FAILED" - The processing failed (see failureReason for details)

Allowed values:

metricsobject

Metrics about the parsing process.

configobject

The configuration used for the parsing process, including any default values that were applied.

ocrobjectOptional

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

failureReasonstringOptional

The reason for failure if status is "FAILED".

usageobjectOptional

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.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error

422

Unprocessable Entity Error

500

Internal Server Error

Authentication

Headers

Query parameters

Request

Response

Errors