> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filerouter.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Pass Provider-Specific Parse Options to Any Provider

> Use providerOptions to pass native settings directly to one provider. Each key is namespaced — options never leak between providers.

FileRouter lets you pass native, provider-specific settings alongside the common parse options you already use. The `providerOptions` object is **namespaced by provider ID** — when you set `providerOptions.llamaparse`, only LlamaParse receives those values. Mistral OCR and Datalab never see them, and vice versa. This means you can safely configure multiple providers in a single `compare` call without any risk of options from one provider interfering with another.

## How namespacing works

Each key in `providerOptions` must match a provider ID (`llamaparse`, `mistral-ocr`, or `datalab`). FileRouter extracts the matching namespace before forwarding the request to each provider. Providers that don't have a matching key in `providerOptions` receive no extra options at all.

FileRouter also applies the input source and all authentication-owned fields **after** any native options you supply. This means provider options cannot redirect a job to a different endpoint or override credentials — the routing is always under FileRouter's control.

<Note>
  If you request a normalized output that a provider doesn't support (for example, asking for `tables` from a provider that has no table capability), FileRouter fails the request **before** sending anything to the provider. You get an immediate error rather than a silent empty result.
</Note>

## Passing options to a single provider

Use `providerOptions` in a `parse` call to send typed native settings to one provider:

```ts title="Parse with LlamaParse agentic options" theme={null}
const result = await router.parse(file, {
  outputs: ['markdown', 'images'],
  pages: [1, 3],
  provider: 'llamaparse',
  providerOptions: {
    llamaparse: {
      agentic_options: { custom_prompt: 'Preserve footnotes' },
      tier: 'agentic',
    },
  },
})
```

The `tier` and `agentic_options` fields map directly to LlamaParse's official SDK request type. Page numbers are always one-based in FileRouter and are translated into each provider's native representation automatically.

## Passing different options per provider in a compare call

Because `providerOptions` is namespaced, you can include options for multiple providers in a single `compare` call. Each provider only receives its own block:

```ts title="Compare with per-provider options" theme={null}
const result = await router.compare(file, {
  outputs: ['markdown', 'tables'],
  providerOptions: {
    llamaparse: {
      tier: 'cost_effective',
    },
    'mistral-ocr': {
      model: 'mistral-ocr-latest',
      includeImageBase64: false,
    },
  },
})
```

LlamaParse receives the `tier` field. Mistral OCR receives `model` and `includeImageBase64`. Neither provider sees the other's options.

<Tabs>
  <Tab title="LlamaParse options">
    LlamaParse options follow `ParsingCreateParams` from `@llamaindex/llama-cloud`. Protected fields (`file_id`, `source_url`, `organization_id`, `project_id`) are stripped automatically — you cannot override them through `providerOptions`.

    ```ts title="LlamaParse native options reference" theme={null}
    providerOptions: {
      llamaparse: {
        // Tier controls speed and quality trade-off
        tier: 'agentic' | 'agentic_plus' | 'cost_effective' | 'fast',
        // Pass a custom prompt for the agentic tier
        agentic_options: { custom_prompt: string },
        // Any other ParsingCreateParams fields (except protected ones)
      },
    }
    ```
  </Tab>

  <Tab title="Mistral OCR options">
    Mistral OCR options follow `OCRRequest` from `@mistralai/mistralai`, minus the `document` field (FileRouter sets that from your input). All other fields in `OCRRequest` are valid.

    ```ts title="Mistral OCR native options reference" theme={null}
    providerOptions: {
      'mistral-ocr': {
        model: 'mistral-ocr-latest',
        includeImageBase64: true,
        tableFormat: 'markdown' | 'html',
        // Any other OCRRequest fields except 'document'
      },
    }
    ```
  </Tab>

  <Tab title="Datalab options">
    Datalab options map directly to the Convert API fields. Use the `raw` sub-key for any fields that FileRouter doesn't yet expose as typed properties.

    ```ts title="Datalab native options reference" theme={null}
    providerOptions: {
      datalab: {
        mode: 'accurate' | 'balanced' | 'fast',
        use_llm: true,
        paginate: true,
        // Pass newly-released Datalab fields not yet typed in FileRouter
        raw: { some_new_field: 'value' },
      },
    }
    ```
  </Tab>
</Tabs>

## The `raw` escape hatch

Each configured provider exposes its underlying SDK client through `provider.raw`. You can use this to call provider APIs that FileRouter doesn't currently expose as part of its normalized contract:

```ts title="Access the underlying LlamaParse SDK client" theme={null}
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 }),
  },
})

// Access the native LlamaCloud client directly
const nativeClient = router.provider('llamaparse').raw
```

<Warning>
  Operations performed through `provider.raw` bypass FileRouter's normalization, input validation, and output selection. Use the escape hatch only for features that the FileRouter SDK doesn't yet support natively.
</Warning>

## Provider output capabilities

<Accordion title="Which outputs does each provider support?">
  | Output     | LlamaParse | Mistral OCR | Datalab |
  | ---------- | ---------- | ----------- | ------- |
  | `markdown` | ✓          | ✓           | ✓       |
  | `text`     | ✓          | —           | —       |
  | `pages`    | ✓          | ✓           | —       |
  | `tables`   | ✓          | ✓           | —       |
  | `images`   | ✓          | ✓           | ✓       |
  | `json`     | ✓          | ✓           | ✓       |
  | `metadata` | ✓          | ✓           | ✓       |
  | `html`     | —          | —           | ✓       |
  | `chunks`   | —          | —           | ✓       |

  Requesting an output that a provider doesn't support fails immediately, before any provider I/O occurs.
</Accordion>