Compare Document Parsing Across Multiple Providers

router.compare(input, options) sends one document to multiple providers at the same time and returns a single CompareResult containing each provider’s output. This is the fastest way to evaluate which provider performs best on your document type before committing to one in production. Both FileRouter (BYOK) and FileRouterClient (hosted) expose the same compare() signature.

How compare() resolves the input

FileRouter resolves the input document once before dispatching to providers. If you pass a ReadableStream, it is consumed a single time and converted to replayable bytes so every provider receives identical data. This also means you can safely pass a File or Blob without worrying about the stream being exhausted.

CompareOptions

providers

Array<string>

The IDs of the providers you want to compare (e.g. ['llamaparse', 'mistral-ocr']). When omitted, the router runs all configured providers concurrently.

outputs

Array<string>

default:"['markdown']"

The output types to request from each provider. Available values match ParseOptions: 'chunks', 'html', 'images', 'json', 'markdown', 'metadata', 'pages', 'tables', 'text'. A provider that does not support a requested output will appear in the result with status: 'unsupported' rather than failing the whole comparison.

pages

Array<number>

One-based page numbers to process. When omitted, all pages are processed. The router translates these into each provider’s native representation.

providerOptions

ProviderParseOptions

Namespaced provider-specific options. Only the options matching a given provider’s key are forwarded to that provider — settings for one provider are never sent to another.

providerOptions: {
  llamaparse: { tier: 'premium' },
  'mistral-ocr': { /* Mistral-specific fields */ },
}

includeRaw

boolean

default:"false"

Set to true to include each provider’s complete native response in its ParseResult.raw field.

timeoutMs

number

default:"600000"

Maximum time in milliseconds to wait for all providers to complete. Defaults to 10 minutes.

signal

AbortSignal

An AbortSignal for cancelling the operation.

CompareResult

The result contains top-level metadata about the comparison and a providers array with one entry per provider.

providers

Array<CompareProviderResult>

An array of per-provider results, one entry per provider that was run.

Show CompareProviderResult fields

provider

string

The provider ID (e.g. 'llamaparse').

status

'parsed' | 'failed' | 'unsupported'

Whether the provider succeeded, failed, or reported the requested output as unsupported.

result

ParseResult

The full ParseResult for this provider. Present only when status is 'parsed'. See ParseResult for the full shape.

error

object

An error summary with message and optional code. Present only when status is 'failed' or 'unsupported'.

durationMs

number

How long this provider took to respond, in milliseconds.

outputs

Array<string>

The output types that were requested for this comparison run.

input

string

A description of the input document (e.g. the filename or URL).

timing

object

Timing information for the overall comparison with startedAt, completedAt (ISO 8601 strings), and durationMs.

Complete example

The example below compares LlamaParse and Mistral OCR on the same PDF and prints the Markdown output from each provider that succeeded.

compare-providers.ts

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

const router = new FileRouter({
  providers: {
    llamaparse: llamaparse(),
    'mistral-ocr': mistralOcr(),
  },
})

const comparison = await router.compare('https://example.com/invoice.pdf', {
  providers: ['llamaparse', 'mistral-ocr'],
  outputs: ['markdown'],
})

console.log(`Comparison took ${comparison.timing.durationMs}ms total`)

Iterating over the result

iterate-compare-result.ts

for (const entry of comparison.providers) {
  if (entry.status === 'parsed' && entry.result) {
    console.log(`\n--- ${entry.provider} (${entry.durationMs}ms) ---`)
    console.log(entry.result.outputs.markdown)
  } else {
    console.warn(
      `${entry.provider} ${entry.status}: ${entry.error?.message}`
    )
  }
}

A compare() call counts as one parse job per provider against your usage. Running three providers on a 50-page document counts as three 50-page parse jobs.

When you need to pinpoint which provider caused a problem, check error.code on the failed CompareProviderResult entry. You can also use the providerId field on a FileRouterError if you catch one from a standalone parse() call — see Errors for details.

Get Started

Core Concepts

TypeScript SDK

CLI

Guides

Compare Document Parsing Across Multiple Providers

How compare() resolves the input

CompareOptions

CompareResult

Complete example

Iterating over the result

​How compare() resolves the input

​CompareOptions

​CompareResult

​Complete example

​Iterating over the result

How compare() resolves the input

CompareOptions

CompareResult

Complete example

Iterating over the result