Last reviewed: 2026-08-09

Direct answer

A PDF budget should not be based on file size alone. Treat each document as a combination of extracted text, page imagery, instructions, expected output, and bounded retries. Page count is a useful admission-control field, but it is not a portable token estimate: a text-heavy contract, a scanned form, and a chart-dense report can consume very different amounts of context.

Build the initial budget from a representative sample of the actual document class. Measure input usage for ordinary pages, dense pages, and pages with important visual content. Keep separate measurements for every supported visual-detail mode and model route. Then calculate a ceiling rather than relying on the average:

budgeted_input_tokens = fixed_prompt_tokens
                      + (approved_pages * measured_p95_input_tokens_per_page)

maximum_run_cost = (budgeted_input_tokens * current_input_rate)
                 + (output_token_cap * current_output_rate)
                 + retry_cost_reserve

The rates must come from the currently approved provider contract or pricing record. The measured page value must come from the same provider, model, input method, and visual mode intended for production. If any of those inputs change, the estimate is stale.

Before sending a full document, enforce a page ceiling, byte ceiling, input-token ceiling, output-token ceiling, and retry ceiling. A request should proceed only when all five pass. A byte limit protects the transport contract; it does not prove that the document fits the context window or the cost budget.

Who this is for

This workflow is for platform engineers who accept PDFs into AI applications, FinOps teams that allocate model spend, and product owners who must preserve document-analysis quality without leaving input cost open-ended. It is particularly useful for financial reports, legal documents, scanned forms, research papers, and other workloads where charts or page layout may matter.

It also gives reviewers a common contract. Engineering owns the measured usage and enforcement point. The workload owner decides which visual details are necessary. The cost owner approves the ceiling and exception path. No single team has to infer the entire budget after the invoice arrives.

Key takeaways

  • Page count is an admission-control input, not a universal token conversion factor.
  • Measure text-heavy, image-heavy, and mixed pages separately before setting a production ceiling.
  • Make visual detail an explicit workload setting. Do not silently inherit a provider default.
  • Cap output and retries alongside input because all three affect the maximum run cost.
  • Record estimated and actual usage without logging document contents, extracted text, filenames, or source URLs.
  • Revalidate the budget whenever the model, provider route, parsing mode, or document mix changes.
  • Use the preflight token-counting workflow to connect the estimate to an approval gate.

Sources checked

The OpenAI file-input documentation says vision-capable models receive both extracted text and page images from PDFs. It also documents auto, low, and high PDF detail settings in the Responses API. That means an operator should record the selected detail level and should not treat a run measured in one mode as evidence for another.

The Google document-understanding documentation describes native visual processing of text, images, diagrams, charts, and tables in PDFs, including documents up to 1,000 pages. It documents an estimate of 258 tokens per document page under its stated processing rules and recommends the Files API for larger or repeatedly referenced documents to reduce request latency and bandwidth. This is a provider-specific planning input, not a cross-provider constant.

The Anthropic PDF-support documentation lists a 32 MB maximum request size, subject to platform variation, and up to 600 pages, reduced to 100 when the request context window is below one million tokens. It warns that dense PDFs can fill the context window before those limits. It also estimates 1,500 to 3,000 text tokens per page, depending on content density, with image processing accounted for separately. Those figures show why page budgeting must remain route-specific.

These sources describe different processing contracts. Do not average their numbers or substitute one provider’s page estimate for another provider’s usage field.

Contract details to verify

Define the workload contract

Record these fields before approving a PDF workload:

  • Workload owner and cost owner.
  • Document class, such as annual report, invoice, or scanned application.
  • Provider route and model family.
  • Input method, such as inline data, uploaded file reference, or supported external file URL.
  • Maximum file bytes and pages per request.
  • Visual-detail mode and the reason it is required.
  • Sample size, sampled page types, and measured input-token distribution.
  • Fixed prompt size, output-token cap, retry cap, and maximum run cost.
  • Fallback action when the request exceeds a limit.
  • Review trigger for model, route, parser, prompt, or document-mix changes.

File limits must be copied from the exact route being used. For example, Anthropic notes that its request limits include other content sent alongside the PDF, and that encrypted or password-protected PDFs do not meet its standard PDF requirement. A nominally valid page count can therefore still fail because the complete payload is too large or the context fills early.

Visual behavior also depends on the route. Anthropic documents a specific Amazon Bedrock Converse behavior in which full visual PDF analysis requires citations; without that setting, the route falls back to basic text extraction. A successful response is therefore not enough evidence that charts were actually analyzed. The acceptance test must include known visual facts.

Happy-path workflow

  1. Validate the file type, page count, byte size, orientation, and selected route before model invocation. Reject unsupported encryption or malformed files.
  2. Classify the request as text-first, mixed, or visually essential. Use the least detailed mode that passes the workload’s quality test.
  3. Sample representative pages, including at least one ordinary page, one dense page, and one chart or image page when those exist. Run the sample through the production model and mode.
  4. Calculate the input ceiling from the measured high-percentile page usage, fixed prompt, and a documented margin. Add separate output and retry ceilings.
  5. Send one canary document. Compare provider-reported actual usage with the estimate before opening normal traffic.
  6. Allow the workload only when the document and projected run fit every approved ceiling.
  7. Reconcile actual input, output, errors, and retries after the run. The usage reconciliation workflow provides a related ledger pattern.

A sanitized decision log can look like this:

{
  "event": "pdf_budget_check",
  "run_ref": "run-042",
  "document_ref": "doc-042",
  "provider": "provider-a",
  "model_family": "vision-model",
  "page_count": 84,
  "file_bytes": 9200000,
  "visual_detail": "low",
  "sampled_pages": 6,
  "estimated_input_tokens": 42000,
  "input_token_cap": 50000,
  "actual_input_tokens": 38740,
  "output_token_cap": 1200,
  "actual_output_tokens": 744,
  "retry_count": 0,
  "decision": "allow",
  "error_class": null
}

Keep document contents, extracted passages, original filenames, upload handles, request headers, and source URLs out of cost logs. Use a short internal reference that resolves through the application’s normal access controls.

Error-path workflow

If preflight exceeds a ceiling, stop before invocation and return a budget decision, not a generic model error. Offer one of three controlled actions: select only the relevant page range, split the document into approved sections, or request a documented exception. Lower visual detail only when the workload owner confirms that the quality test still passes.

If the provider rejects a request for size, context, format, or route configuration, classify the error before retrying. Do not resubmit the same payload automatically. Mark cost as unresolved until provider-reported usage is reconciled, then recompute the remaining retry allowance. If actual input usage exceeds the estimate threshold during a canary or batch, close the admission gate, preserve the sanitized measurements, and rebaseline the document class.

Failure modes

The team treats the provider page maximum as a safe operating target. A documented maximum is not a budget recommendation. Dense pages and other request content can consume the context first. Set an internal ceiling from measured usage and keep it below the applicable technical limit.

A low-detail mode passes cost review but fails the product task. Small labels, footnotes, and chart legends may carry the answer. Include visual ground-truth questions in the acceptance set, and approve low detail only when those questions still pass. The related vision resolution guardrails can help separate quality requirements from cost preferences.

A route silently performs text-only extraction. This can produce fluent answers while omitting charts. Verify route-specific feature settings and test against information that exists only in an image or visual layout.

Retries multiply an already large input. A timeout handler that resends the full PDF can turn one budgeted request into several. Permit retries only for classified transient failures, enforce an attempt cap, and include the reserve in the original approval.

The byte check passes while the context check fails. Compressed PDFs can be small on disk but dense after text extraction and page rendering. Maintain independent byte, page, and measured-token controls.

The team assumes an uploaded-file reference makes inference free. File APIs can reduce repeated transfer overhead or latency, but the model request still needs its own usage reconciliation. Do not book savings until metered results demonstrate them.

Actual usage cannot be tied back to the decision. Missing model, detail mode, page count, or retry fields makes variance analysis speculative. Reject incomplete ledger records rather than filling them with guessed values.

FAQ

Can file size predict PDF token use?

Not reliably. File size is affected by compression, fonts, embedded images, and scanning choices. It remains useful for enforcing a provider payload limit, but measured usage from representative pages is the better budget input.

Should every PDF use high visual detail?

No. Text-first documents may pass their quality test at a lower detail level, while diagrams or small-print tables may require more visual information. Make the choice per document class and preserve the test evidence.

Is a fixed tokens-per-page value portable across providers?

No. The checked documentation describes materially different processing and estimation rules. Even within one provider, model, route, visual mode, and page density can change the result. Treat documented estimates as preflight inputs and provider-reported usage as reconciliation evidence.

What should happen when one document exceeds the cap?

Do not quietly raise the cap. Select an approved page range, split the work into bounded sections, or send the request through the exception process. Each section still needs its own output and retry limits, and the combined job needs a parent ceiling.

Does reusing an uploaded file guarantee lower model cost?

No. Reuse may reduce upload bandwidth or latency, depending on the provider contract. It does not by itself prove lower inference-token charges. Compare metered runs before recording savings.

How large should the safety margin be?

There is no universal percentage. Derive it from the observed variance of the document class, then review it as the sample grows. A new parser, model, or document source invalidates that evidence and should trigger a new canary.

Reader next step

Select a small, representative set of production-safe PDFs and divide their pages into ordinary, dense-text, and visually essential groups. Measure each group on the intended provider route and detail mode. Set page, byte, input, output, retry, and cost ceilings from those results, then run a single canary through the happy and error paths above.

Do not open normal traffic until the canary’s provider-reported usage can be reconciled to its decision record. Once that works, add the gate to deployment change control and review it whenever the route or document mix changes.