Parse File | extend

import { ExtendClient } from "extend-ai";
const client = new ExtendClient({ token: "YOUR_TOKEN" });
await client.parse({
    file: {
        url: "https://example.com/bank_statement.pdf",
        name: "bank_statement.pdf"
    }
});

{
  "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
            }
          },
          "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,
      "verticalGroupingThreshold": 1,
      "returnOcr": {
        "words": 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
      }
    ]
  },
  "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.

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](https://docs.extend.ai/2025-04-21/product/parsing/parse).

Authentication

AuthorizationBearer

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

Headers

x-extend-workspace-idstringOptional

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 for details on API key scopes.

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.

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

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.

ocrobject

Raw OCR data from the parsing process. Only included when returnOcr is configured in the parse config’s advanced options.

failureReasonstring

The reason for failure if status is "FAILED".

usageobject

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

404

Not Found Error

422

Unprocessable Entity Error

500

Internal Server Error