LlamaIndex Parse Gateway: Page-Level PDF Routing Guide

LlamaIndex Parse Gateway estimates page complexity, assigns simple text pages to LiteParse, and selects cost_effective, agentic, or agentic_plus parsing for harder pages. This can avoid processing every page at the highest tier, but it does not keep the non-selected pages out of LlamaCloud: the current parse.ts uploads the same complete PDF separately for each non-empty cloud-tier group and supplies page numbers to limit parsing. The useful production pattern is page-level classification plus observable fallback; the public app itself remains a small source-available demo.

What Parse Gateway is—and is not

The repository was created July 10, 2026. Its README describes a TanStack Start application with a single server route that accepts a PDF, runs LiteParse complexity estimation, fans pages out to local and cloud parsers, and streams status through Server-Sent Events (SSE).

Do not label the repository MIT, Apache-2.0 or “open-source” without a license grant. If your organization wants to reuse its code, ask LlamaIndex for written terms or reimplement the documented behavior from independently reviewed requirements.

This architecture is adjacent to general model routing. The OmniRoute AI gateway guide covers request routing at the model layer; Parse Gateway makes a similar decision at the PDF-page layer.

Follow the request and control flow

The demo's main components are small enough to reason about:

The control flow is:

PDF upload
  -> estimate every page
  -> derive OCR baseline tier
  -> optionally raise tier from layout signals
  -> group page numbers by final tier
  -> parse simple pages locally
  -> for each non-empty cloud tier, upload the complete PDF
  -> ask LlamaParse to process that tier's selected page numbers
  -> stream status and page results
  -> sort by original page number
  -> render/export combined Markdown

The final merge is as important as the parser choice. A pipeline that silently omits a timed-out page can look successful while producing an incomplete document.

Run the demo locally

The README's shortest path is:

# Starting commands from the repository README; not executed for this guide.
git clone https://github.com/run-llama/parse-gateway.git
cd parse-gateway
pnpm install
pnpm dev

The development app listens on local port 3000. A LlamaParse Platform API key is needed only when pages escalate beyond local LiteParse. The README also lists:

# Production-build commands from the README; not a production-readiness claim.
pnpm build
pnpm start

pnpm start uses Vite preview and defaults to port 4173 through $PORT. Vite preview is not by itself an application security, scaling or availability architecture.

Before uploading sensitive documents:

1. inspect the current repository revision and dependencies;
2. run it on a private developer machine;
3. use a short-lived or low-scope test key if the platform supports one;
4. start with synthetic PDFs;
5. assume the complete PDF leaves the machine if any page escalates, and inspect whether multiple cloud tiers cause repeated full-document uploads;
6. delete browser storage and generated output after the trial.

Understand the routing decisions

The official blog and README map each OCR reason to a baseline:

Magnitude can raise a baseline. The demo also escalates an agentic page to agentic_plus when three or more OCR reasons fire, because independent defects compound.

The README intends layout to be a separate, optional input:

When layout escalation is enabled, the final tier is the maximum selected by OCR and layout rules. Layout can only raise, never lower, the result.

The current implementation does not fully match the README's promise that disabling the toggle produces purely OCR-based routing. In src/routes/api/is-complex.ts at the reviewed revision, the initial local-versus-cloud branch still checks layout.isComplex even when include_layout is false. A page with no OCR requirement but complex layout can therefore miss the local branch and fall through to a cloud tier, although the later layout-escalation function is disabled. Treat this as a current source/README mismatch and test the actual revision before relying on the toggle.

Production policy wrapper

Do not bury these thresholds inside unversioned application code. Wrap them in a policy record:

# Illustrative routing policy, not the repository's configuration format.
policy_version: "pdf-routing-2026-07-31"
estimator:
  package: "@llamaindex/liteparse"
  version: "<pinned-version>"
routing:
  local_when:
    ocr_reasons: []
    layout_complex: false
  compound_escalation:
    minimum_ocr_reasons: 3
  layout_enabled: true
fallback:
  on_estimator_error: "quarantine"
  on_cloud_timeout: "retry-once-then-review"
  on_missing_page: "fail-document"

Pinning the policy makes a cost or accuracy shift explainable after a dependency upgrade.

Secure the browser-to-server API-key boundary

The README says the API key is stored in browser localStorage, sent as a bearer token to /api/parse, and never persisted server-side. That is transparent demo behavior, but “not persisted on the server” is not the same as “safe.”

Page-number filtering limits which pages a cloud parse job processes; it does not limit which bytes the current demo uploads. A production review should therefore classify and approve the document as a whole before any cloud route is allowed. If page-level confidentiality is required, split or redact the document before the provider boundary and verify that the resulting files cannot reconstruct excluded content.

A production application should authenticate the user to your backend, authorize the document and requested policy, retrieve the provider credential from a secret manager, and proxy only the allowed operation. Never return the provider secret to browser JavaScript.

Design failure and fallback behavior

Routing saves money only if it does not hide incomplete output.

The public demo streams live state; a production service should keep durable server-side job state so a phone sleep, tab close or proxy timeout does not destroy observability.

Measure cost without inventing prices

LlamaParse prices are volatile and tier-specific. Retrieve current official pricing when you run the evaluation rather than copying a number into code or this article.

Use:

cloud_parse_cost =
  pages_cost_effective * current_cost_effective_unit
  + pages_agentic * current_agentic_unit
  + pages_agentic_plus * current_agentic_plus_unit

total_pipeline_cost =
  cloud_parse_cost
  + local_compute
  + storage_and_transfer
  + retry_cost
  + quality_review_cost

For each corpus, report:

Compare at least three policies: all-local where feasible, all-highest-tier, and page routing. Hold the corpus and acceptance rubric fixed. The routing policy wins only if it meets the required quality and completeness at a better cost/latency point.

Use the parsing MCP tools carefully

The live official tools/list response from https://mcp.llamaindex.ai/parse/mcp, checked July 31, 2026, exposes this storage and parsing sequence:

• getUploadUrl returns a pre-signed URL for LlamaParse S3 storage.
• uploadFileByUrl downloads a file from the supplied URL and places it in LlamaParse S3 storage.
• estimateFileComplexity requires a file ID obtained from one of those upload tools or supplied by the user.
• parseWithLiteParse also requires such a file ID; its in-process parser consumes no LlamaParse Platform credits, but the referenced document is already in the provider's file-storage boundary.

Zero provider price and in-process LiteParse execution do not mean the document remains on the caller's machine when these MCP tools are used. This gives an agent a routing decision, not permission to upload any document. Wrap upload and parse calls with document-level classification, destination, retention and cost policy. Record the document digest, tool name, server identity, arguments, storage decision, route decision and returned page manifest.

For a broader view of agent-facing MCP permissions and review surfaces, see the GitHub Copilot agent skills and MCP guide.

Prepare a production implementation

• Obtain an explicit license or reimplement from reviewed requirements.
• Pin LiteParse, LlamaCloud client and routing-policy versions.
• Move provider credentials out of browser storage.
• Authenticate users and authorize document classes server-side.
• Reject oversized, encrypted, malformed or unsupported files predictably.
• Scan uploads and isolate parser execution.
• Use durable jobs rather than relying only on one SSE connection.
• Add idempotency keys for cloud parse retries.
• Emit a page manifest with one terminal status per source page.
• Fail the document when a page is missing, duplicated or out of order.
• Redact bearer tokens, document text and sensitive metadata from logs.
• Add retry budgets, circuit breakers and provider quota alerts.
• Measure quality by document class, not only average extraction success.
• Retrieve official current prices and store the dated cost calculation.
• Retain a manual review route for ambiguous or high-impact documents.
• Test restore, deletion and provider-key rotation.

If you plan to host the service yourself, the OpenShip deployment guide covers surrounding build and runtime concerns. It does not resolve Parse Gateway's absent license.

Official sources

LlamaIndex

• Parse Gateway: Smart, Page-Level Document Parser Routing — routing rationale, OCR reason baselines, layout escalation and MCP tools
• Parse Gateway repository — source, architecture, creation date, release and license state
• Parse Gateway README — app flow, startup commands, SSE behavior and API-key handling
• Parse route at reviewed revision — complete-file upload for each non-empty cloud-tier group plus page-number filtering
• Complexity route at reviewed revision — current layout-toggle control flow
• LlamaIndex parsing MCP endpoint — official parsing tool endpoint
• LlamaParse API key documentation — current authentication setup

Related AgentPedia guides

• OmniRoute AI gateway routing guide
• GitHub Copilot agent skills and MCP guide
• OpenShip self-hosted deployment guide