File Size Limits and Large Document Uploads with FileRouter

Every document you submit to FileRouter flows through one of two paths: the hosted service (managed credentials, durable jobs, result storage) or a direct BYOK call through the FileRouter SDK class (your own provider keys, provider’s own limits apply). Understanding which path you’re on determines which size limits apply to your uploads.

Hosted service: 100 MB upload ceiling

The hosted FileRouter API accepts files up to 100 MB per request. When you upload a binary file, it streams securely into storage — FileRouter never buffers the entire file during ingress.

Upload a file to the hosted service

import { FileRouterClient } from '@file_router/sdk'

const client = new FileRouterClient({ apiKey: process.env.FILEROUTER_API_KEY })

// Files up to 100 MB stream directly into storage
const result = await client.parse(largeFile, {
  outputs: ['markdown'],
  provider: 'llamaparse',
})

In production, FileRouter gives each provider a short-lived, scoped source URL to fetch the document securely. The document is processed directly by the provider and is never re-buffered by the service. After the provider completes, the uploaded source is deleted.

Binary uploads use request headers

When you upload a binary file (rather than a JSON body with a URL), the SDK sets the job parameters as HTTP headers instead of a JSON body. The file bytes become the raw request body. The SDK handles this automatically — you don’t need to construct these headers yourself.

Header	Purpose
`X-FileRouter-Operation`	`parse` or `compare`
`X-FileRouter-Outputs`	Comma-separated output list (e.g. `markdown,tables`)
`X-FileRouter-Filename`	URL-encoded original filename
`X-FileRouter-Provider`	Provider ID for parse operations
`X-FileRouter-Providers`	Comma-separated provider IDs for compare operations
`X-FileRouter-Pages`	Comma-separated one-based page numbers
`X-FileRouter-Include-Raw`	`true` or `false`
`X-FileRouter-Provider-Options`	URL-encoded JSON of the `providerOptions` object
`Content-Type`	The file’s MIME type

URL inputs

Instead of uploading a binary file, you can pass a publicly accessible HTTP or HTTPS URL. FileRouter (or the downstream provider) fetches the document directly from that URL:

Parse a document by URL

const result = await client.parse('https://example.com/annual-report.pdf', {
  outputs: ['markdown', 'tables'],
  provider: 'mistral-ocr',
})

URL inputs send a JSON body rather than a binary stream, so the 100 MB hosted upload ceiling does not apply to the URL itself. The provider fetches the document directly, subject to that provider’s own download limits and timeout policies.

The URL must be publicly accessible over HTTP or HTTPS. FileRouter cannot fetch documents from localhost, private networks, or URLs requiring authentication headers. Use a public development tunnel when testing with local files during hosted development.

Files above 100 MB

For files larger than 100 MB, you have two options:

BYOK direct mode (SDK)
CLI with --local flag

Use the FileRouter class directly with a provider adapter. This bypasses the hosted service entirely — your document goes straight to the provider using your own API key. The 100 MB ceiling doesn’t apply; each provider’s own file-size limits govern the request.

BYOK direct mode — bypasses the hosted ceiling

import { FileRouter } from '@file_router/sdk'
import { llamaparse } from '@file_router/sdk/llamaparse'

const router = new FileRouter({
  providers: {
    llamaparse: llamaparse({
      apiKey: process.env.LLAMA_CLOUD_API_KEY,
    }),
  },
})

// No hosted ceiling — LlamaParse's own limits apply
const result = await router.parse(veryLargeFile, {
  outputs: ['markdown'],
  provider: 'llamaparse',
})

Provider responses — especially those with extracted images or raw JSON output — can be large. Pass includeRaw: true only when you genuinely need the full provider response. Omitting it keeps memory usage and response sizes lower.

The CLI’s --local flag routes the job through BYOK direct mode. Set the provider’s standard environment variable and add --local to your command:

Parse a large file locally with BYOK

LLAMA_CLOUD_API_KEY=your-key npx @file_router/cli parse large-document.pdf --local

Use Mistral OCR locally

MISTRAL_API_KEY=your-key npx @file_router/cli parse large-document.pdf --local --provider mistral-ocr

The --local flag bypasses the hosted service and the 100 MB ceiling. The file is submitted directly to the provider from your machine.

Provider native file limits

In BYOK direct mode, each provider enforces its own size and format limits independently of FileRouter. Consult each provider’s documentation for their current ceilings. FileRouter normalizes errors from providers into FileRouterError with a ParseFailed code, so your error handling doesn’t need to be provider-specific.

Result retention

How long are results available?

Hosted job results are available for 7 days after the job completes. After 7 days, requesting the job returns HTTP 410 Gone. Job records themselves are removed after 30 days.If you need results beyond the 7-day window, retrieve and store the result data in your own storage before it expires.

Handle expired results gracefully

try {
  const result = await client.parse(file, { outputs: ['markdown'] })
  // Store result.outputs.markdown in your own storage
} catch (error) {
  if (error.status === 410) {
    // Result has expired — resubmit the job
  }
}

Summary

Scenario	Ceiling	How to handle
Hosted binary upload	100 MB	Use BYOK direct mode or URL input for larger files
Hosted URL input	No hosted ceiling	Provider fetches directly; provider limits apply
BYOK direct mode (SDK)	Provider’s own limits	Use `FileRouter` class + provider adapter
CLI `--local`	Provider’s own limits	Add `--local` flag; set provider env var
Result availability	7 days	Fetch and store results before expiry

Get Started

Core Concepts

TypeScript SDK

CLI

Guides

File Size Limits and Large Document Uploads with FileRouter

Hosted service: 100 MB upload ceiling

Binary uploads use request headers

URL inputs

Files above 100 MB

Provider native file limits

Result retention

Summary

​Hosted service: 100 MB upload ceiling

​Binary uploads use request headers

​URL inputs

​Files above 100 MB

​Provider native file limits

​Result retention

​Summary

Hosted service: 100 MB upload ceiling

Binary uploads use request headers

URL inputs

Files above 100 MB

Provider native file limits

Result retention

Summary