Documents

Everything else, including HTML and SVG, is rendered in a browser and captured as a page. See Browser Behavior.

One more kind of URL is not a page: a YouTube video, which comes back as its transcript. See YouTube.

URLs without an extension

The extension is only a hint. Fetch looks at what the origin actually serves, so https://arxiv.org/pdf/1706.03762 converts as a PDF even though the URL has no extension, and a .pdf URL that really serves a web page is captured as a page. A spreadsheet served as application/octet-stream still converts.

One exception: a URL with no recognizable extension that serves text/plain is captured as a rendered page. Give it a .txt or .md extension, or serve text/markdown, to get the text back verbatim.

What comes back

The response shape is the one you already handle. A converted document fills markdown and adds a reference to the original file:

Use POST /v1/fetch/json for structured metadata and the original-file link. POST /v1/fetch returns the converted Markdown directly.

The playground previews a document when you fetch it there. A document's snapshot identity does not provide a public browser replay; use data.document.url to share its original file.

State JSON, Appendix, screenshots, and links exist only because a browser rendered something, so a document fetch has none of them. Asking for them does not fail the request. The fields are simply absent.

Conversion limits

documentConfig controls conversion and lets you set a page limit. Every field is optional. When you omit maxPages, Fetch converts the entire PDF and bills the pages it delivers.

auto keeps readable text from each page and sends pages with missing or unreliable text to OCR. OCR runs in batches, and the result keeps the original page order.

never blocks the vision model outright. It is the cheapest and most predictable setting, and it is also the one that returns an empty document for a scanned PDF and nothing at all for an image, since an image has no text layer to fall back on.

always reads every page with the model even where a text layer exists.

Exceed one of these limits and Fetch refuses the request with 413 instead of truncating it. A half-converted document is worse than a clear error, because nothing in the Markdown tells you where it stopped. Refusals cost you no credits.

PDFs have no default page limit or public 50 MB transfer cap. Large PDFs are processed in batches, so the length of the original document does not need to fit one OCR request. Document processing can run for up to 55 minutes once a worker starts. Queue waits use the shorter 150-second capacity budget. Set your HTTP client timeout to allow a long conversion to finish.

Worker resource protection still applies. Resource exhaustion is a processing failure, not a 413 page-limit refusal. Image and audio conversion also depend on their providers' limits.

Pricing

Converting a document costs credits on top of the one-credit Fetch. 1,000 credits cost $1.

Office files, ebooks, CSV, TSV, JSON, XML, and text convert locally and add nothing. Those fetches cost the flat one credit.

A 12-page PDF with a good text layer costs 1 + 12 = 13 credits. The same document scanned, with no text layer, costs 1 + 12 + 12 × 5 = 73 credits. That gap is the reason ocr and maxPages exist. See Pricing & Usage.

Batched Fetch reports the units each item spent as data.usage, which you can price with the table above:

Errors

Document fetches report these outcomes:

An upcoming response will report document refusals as 200 FetchOriginError with contentAvailable: false, originStatusCode, and a retryable verdict. Support both shapes during the transition. See Error Handling.

An over-limit document returns 413 FetchPageTooLarge, the same error an oversized page returns. The Errors reference has the full list and the payload shapes.

A document fetch reports the origin's status instead of converting an error page into Markdown. That is deliberately unlike a page fetch, which renders whatever the origin served and puts the status in originStatusCode. Rendering the error page is right for a caller who asked for a page. There is no rendering step here, so the only alternative would be handing you a block page and calling it your document.

Batched Fetch

Batched Fetch does not convert documents yet. Every URL in a batch goes to the browser, so a document URL comes back as a failed item rather than as Markdown. The batched endpoint accepts documentConfig but ignores it.

Send document URLs to POST /v1/fetch or POST /v1/fetch/json until this lands.

Next steps

• Include Options: choose what a fetch returns.
• Playground & Replay: inspect a converted document next to its original.
• Pricing & Usage: see what converted pages and audio cost in credits.
• Errors: handle 415, 502, and 503 in your client.