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

# Provider Routing

> Route requests across providers for the same model

You can specify a model without a provider prefix (e.g., `gpt-oss-120b` instead of `groq/gpt-oss-120b`), and the API will automatically select a provider for you. Optionally, use the `model_selection.provider` field in your router config to control how providers are selected.

By default, the provider with the lowest latency is selected, and if it fails, the next best provider is tried automatically.

<Note>
  See all models via the [List Models](/api-reference/modelsAPI/modelservice/list-models) endpoint. Current supported providers include OpenAI, Anthropic, Google Vertex AI, Google AI Studio, Cerebras, DeepInfra, Fireworks, Mistral, Groq, and xAI. [Contact us](https://inworld.ai/contact-sales) to request a provider or model to be supported.
</Note>

## Provider configuration

| Field             | Type       | Default | Description                                                                                           |
| :---------------- | :--------- | :------ | :---------------------------------------------------------------------------------------------------- |
| `order`           | `string[]` | -       | Explicit list of providers to try, in order. When specified, providers are tried in this exact order. |
| `allow_fallbacks` | `boolean`  | `true`  | Whether to fall back to the next provider if the first one fails.                                     |

## How provider selection works

When no `provider.order` is specified, the `sort` criteria determines the order providers are tried. If no `sort` is specified either, providers are ordered by latency (fastest first).

When `provider.order` is specified, providers are tried in the exact order listed. `sort` does not apply to the provider order (but still applies to `models` fallbacks if specified).

The `ignore` field applies to providers regardless of whether `order` is specified.

## Examples

<CodeGroup>
  ```json Default (auto provider selection) theme={"system"}
  // Automatically selects the lowest-latency provider for gpt-oss-120b
  // Falls back to next-best provider if it fails
  {
    "variant_id": "auto-provider",
    "model_id": "gpt-oss-120b"
  }
  ```

  ```json Explicit provider order theme={"system"}
  // Try groq first, then fireworks
  {
    "variant_id": "groq-preferred",
    "model_id": "gpt-oss-120b",
    "model_selection": {
      "provider": {
        "order": ["groq", "fireworks"]
      }
    }
  }
  ```

  ```json Sort providers by price theme={"system"}
  // Pick the cheapest provider for gpt-oss-120b
  // Fall back to next-cheapest if it fails
  {
    "variant_id": "cheapest-provider",
    "model_id": "gpt-oss-120b",
    "model_selection": {
      "provider": {
        "allow_fallbacks": true
      },
      "sort": [{ "metric": "SORT_METRIC_PRICE" }]
    }
  }
  ```

  ```json Provider + model fallbacks theme={"system"}
  // Try groq/gpt-oss-120b, then fireworks/gpt-oss-120b,
  // then fall back to gpt-5.4
  {
    "variant_id": "with-fallbacks",
    "model_id": "gpt-oss-120b",
    "model_selection": {
      "provider": {
        "order": ["groq", "fireworks"],
        "allow_fallbacks": true
      },
      "models": ["openai/gpt-5.4"]
    }
  }
  ```

  ```json No provider fallbacks theme={"system"}
  // Try the lowest latency provider only - return error if it fails
  {
    "variant_id": "single-provider",
    "model_id": "gpt-oss-120b",
    "model_selection": {
      "provider": {
        "allow_fallbacks": false
      }
    }
  }
  ```

  ```json Filter by provider theme={"system"}
  // Restrict auto-routing to only use models from specific providers
  // Pairs well with BYOK to ensure requests use your own key
  {
    "model_id": "auto",
    "models": ["openai"]
  }
  ```
</CodeGroup>

## Execution order

When using provider routing with model fallbacks, the full execution order is:

1. **Try providers for the primary model** in `provider.order` order (if specified) or sorted by `sort` criteria (default: latency).
2. **If all providers fail and `models` is specified**, fall back to the models list, sorted by `sort` criteria.
3. **If all models fail**, return an error.

## Use Cases

* **Reliability**: Ensure your application continues working even if a specific provider is down
* **Cost Optimization**: Route to cheaper providers or fall back to cheaper models
* **Performance**: Prefer low-latency providers, or fall back to faster models for time-sensitive requests
* **Provider Control**: Lock to specific providers for compliance or consistency