Process large PDFs with the Files API and page budgeting

TL;DR

Check the limits before anything else. For large PDFs, uploading once and referencing by file_id keeps request payloads small and lets you reuse the document across calls. Query one section at a time with citations enabled so answers point at exact pages. Cross-section synthesis happens in a final pass over the per-section summaries, not in one giant request.

When to use

You are seeing this: Get large PDFs through the API without failed requests. Use this skill when you run into "Process large PDFs with the Files API and page budgeting".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Get large PDFs through the API without failed requests.

1. Check the limits before anything else. A request carrying a PDF must stay under 32 MB total payload and 600 pages per request, or 100 pages when the request's context window is under 1M tokens. Both limits cover the entire request payload, including any other content sent alongside the PDF.
2. Upload with the Files API and reference by fileid. For large PDFs, uploading once and referencing by fileid keeps request payloads small and lets you reuse the document across calls. This is the single biggest reliability win.
3. Budget pages against the context window, not the page cap. Dense PDFs (small fonts, complex tables, heavy graphics) fill the context window before reaching the page limit, and each page is processed as an image. Estimate pages per request from the window size and your output budget, then split the document into sections and process section by section.
4. Downsample embedded images for heavy pages. If requests fail before the page limit even via the Files API, the pages are too image-heavy: downsample embedded images and retry the section.
5. Ask section-sized questions. Query one section at a time with citations enabled so answers point at exact pages. Cross-section synthesis happens in a final pass over the per-section summaries, not in one giant request.
6. Combine with caching for repeat analysis. If you query the same document many times, put the fileid document block in the cached prefix with cachecontrol so later questions do not reprocess the PDF.

Claims verified against Anthropic's official docs (platform.claude.com) on 2026-09-26. Evidence URLs in public_references.