Skip to main content
File parsing converts documents into clean markdown. Add file_parsing_options to an Extract request that points at a document URL.
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.

​
Quick Start

​
Example Request

​
Example Response

​
Supported file types

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

​
object
Enables file parsing. Omit the object to skip parsing and pay only the base Extract price.
​
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.
​
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

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

​
Next steps

Output Formats

Control which data types are returned

Pricing

Per-page rates for each mode