> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# File Parsing

> Convert PDFs, Word documents, spreadsheets, and presentations into markdown during extraction

File parsing converts documents into clean markdown. Add `file_parsing_options` to an Extract request that points at a document URL.

> [!WARNING]
>
> Enabling file parsing adds a per-page-parsed charge on top of the base Extract price. Billing is per page parsed, not per document, and depends on the mode. See [Pricing](https://docs.nimbleway.com/nimble-sdk/admin/pricing.md).

## Quick Start

### Example Request

```bash cURL theme={"system"}
curl -X POST 'https://sdk.nimbleway.com/v2/extract' \
--header 'Authorization: Bearer <YOUR-API-KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://example.com/report.pdf",
    "formats": ["markdown"],
    "file_parsing_options": {
        "mode": "pro",
        "max_pages": 50
    }
}'
```

### Example Response

```json theme={"system"}
{
  "url": "https://example.com/report.pdf",
  "task_id": "8e8cfde7-b311-42f1-8a1c-8f5b6a1c1d11",
  "status": "success",
  "data": {
    "markdown": "# Annual Report\n\n## Revenue\n\n| Quarter | Revenue |\n| --- | --- |\n| Q1 | $4.2M |\n..."
  }
}
```

## Supported file types

| Type | Extensions |
| - | - |
| PDF | `.pdf` |
| Word documents | `.docx` |
| Spreadsheets | `.xlsx`, `.xls`, `.ods`, `.csv` |
| Presentations | `.pptx`, `.ppt`, `.odp` |

Nimble detects the file type from the response `Content-Type` header, the URL file extension, or the file contents. Word documents are detected from their contents. A URL does not need to end in an extension, except for CSV files, which need a `.csv` extension or a `text/csv` content type.

## How it works

**1. Extract downloads the file**

Nimble fetches the document from the URL like any other Extract request.

**2. Page limit check**

If `max_pages` is set and a PDF has more pages, the request fails before parsing.

**3. Parsing**

The document is converted to markdown using the selected `mode`.

**4. Response**

The markdown is returned in `data.markdown`.

## Parameters

> [accordion] file\_parsing\_options
>
> **file\_parsing\_options** `object`
>
> Enables file parsing. Omit the object to skip parsing and pay only the base Extract price.
>
> ```json theme={"system"}
> "file_parsing_options": {
>   "mode": "pro",
>   "max_pages": 50
> }
> ```
>
> **file\_parsing\_options.mode** `string` (default: light)
>
> Parsing mode.
>
> * `light` - Fast, text-native extraction. No OCR.
> * `pro` - Adds LLM-based parsing with OCR fallback for scanned or table-heavy PDFs. Billed at a higher per-page rate than `light`. See [Pricing](https://docs.nimbleway.com/nimble-sdk/admin/pricing.md).
>
> **file\_parsing\_options.max\_pages** `integer`
>
> Maximum number of pages to parse. Minimum `1`. No limit by default.
>
> Rejects PDFs with more pages than this limit with a `file exceeds limit` error. The PDF is not parsed and no parsing charge applies. It does not truncate. Other file types are not page-checked.

## Choosing a mode

| | `light` | `pro` |
| - | - | - |
| Best for | Plain-text documents with a simple, single-column layout | Text-heavy documents with simple tables, and scanned PDFs |
| Tables | Not a focus. Best with plain text. | Simple tables preserved in markdown |
| OCR | No | Yes, as a fallback |
| Cost | Lowest per page | Higher per page |

For example, a 100-page PDF in `pro` costs \$0.75 to parse (100 pages at \$7.50 per 1,000), plus the base Extract price.

## Best practices

* **Start with `light` for digital text.** Use it for text-based documents at high volume. Switch to `pro` if tables come back flat or scanned pages come back empty.
* **Try `pro` for scans.** `light` does not run OCR, so it cannot read pages that are images of text. Test a sample before a large run.
* **Set `max_pages` when PDF sizes vary.** An unexpectedly large PDF is rejected before it is parsed. Other file types are not page-checked.
* **Request only markdown.** Set `formats` to `["markdown"]` to leave the original file out of the response.
* **Expect limited results from charts and dense visual layouts.** Neither mode is built to interpret charts, diagrams, or heavily designed pages.

## Response behavior

* When parsing succeeds, the parsed document is returned in `data.markdown`, whatever `formats` is set to.
* The original file is returned base64-encoded in `data.html` when `formats` includes `html` or when `formats` is not set. Set `formats` to `["markdown"]` to leave it out.
* If parsing fails, the request still succeeds with a warning in the response, and the failed parse is not billed. If `html` was not requested, the original file is returned in `data.html` instead of an empty response.

## Errors

| Condition | Result |
| - | - |
| PDF has more pages than `max_pages` | `400` with `file exceeds limit: <pages> pages, max_pages is <max_pages>`. No parsing charge applies. Raise `max_pages` or omit it. |

## Next steps

> [card] [Output Formats](https://docs.nimbleway.com/nimble-sdk/web-tools/extract/features/formats.md)
>
> Control which data types are returned

> [card] [Pricing](https://docs.nimbleway.com/nimble-sdk/admin/pricing.md)
>
> Per-page rates for each mode


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.