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

# Advanced Routing

> Fine-tune routing with suffix shortcuts, multi-model requests, quality constraints, parameter filtering, custom weights, and data policies

Fine-tune routing with suffix shortcuts, multi-model requests, quality constraints, and data policies. For basic routing, see [Routing options](/guides/routing-options).

## Prerequisites

* An [Auriko API key](https://auriko.ai/signup?redirectTo=%2Fdashboard%3Ftab%3Dapi-keys)
* Python 3.10+ with the OpenAI SDK (`pip install openai`) or the auriko SDK (`pip install auriko`)
  * OR Node.js 18+ with the OpenAI SDK (`npm install openai`) or `@auriko/sdk` (`npm install @auriko/sdk`)
* Familiarity with [Routing options](/guides/routing-options)

## How routing works

When you send a request, Auriko's router:

1. **Enumerates candidates** — finds all providers offering the requested model(s)
2. **Filters by constraints** — removes providers that violate your routing options (data policy, Bring Your Own Key (BYOK) requirement, performance constraints, excluded providers)
3. **Scores by strategy** — ranks remaining candidates using your `optimize` strategy:
   * `cost`: Cost-optimized, well-rounded
   * `cost-focus`: Aggressively minimize cost (default)
   * `ttft`: TTFT-optimized, well-rounded
   * `ttft-focus`: Aggressively minimize time to first token
   * `tps`: Throughput-optimized, well-rounded
   * `tps-focus`: Aggressively maximize tokens per second
   * `balanced`: All dimensions weighted evenly
4. **Selects and routes** — selects from the ranked list, favoring higher-scored providers
5. **Falls back if needed** — if the provider fails and `allow_fallbacks` is true, retries with the next candidate (up to `max_fallback_attempts`)

See [Python SDK](/sdk/python#with-routing-options) or [TypeScript SDK](/sdk/typescript#with-routing-options) for routing code examples.

## Use suffix shortcuts

Append a suffix to any model name for quick routing configuration:

| Suffix        | Strategy     | Description                               |
| ------------- | ------------ | ----------------------------------------- |
| `:cost-focus` | `cost-focus` | Aggressively minimize cost                |
| `:cost`       | `cost`       | Cost-optimized, well-rounded              |
| `:ttft-focus` | `ttft-focus` | Aggressively minimize time to first token |
| `:ttft`       | `ttft`       | TTFT-optimized, well-rounded              |
| `:tps-focus`  | `tps-focus`  | Aggressively maximize tokens per second   |
| `:tps`        | `tps`        | Throughput-optimized, well-rounded        |
| `:balanced`   | `balanced`   | All dimensions weighted evenly            |

<CodeGroup>
  ```python Python OpenAI theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  response = client.chat.completions.create(
      model="gpt-4o:cost-focus",
      messages=[{"role": "user", "content": "Hello!"}]
  )

  response = client.chat.completions.create(
      model="claude-sonnet-4-20250514:ttft",
      messages=[{"role": "user", "content": "Hello!"}]
  )
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o:cost",
      messages: [{ role: "user", content: "Hello!" }],
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  import os
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  # Cost-focused provider for gpt-4o
  response = client.chat.completions.create(
      model="gpt-4o:cost-focus",
      messages=[{"role": "user", "content": "Hello!"}]
  )

  # Fastest time to first token
  response = client.chat.completions.create(
      model="claude-sonnet-4-20250514:ttft",
      messages=[{"role": "user", "content": "Hello!"}]
  )
  ```

  ```typescript TypeScript Auriko theme={null}
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/v1",
  });

  // Cost-focused provider for gpt-4o
  const response = await client.chat.completions.create({
      model: "gpt-4o:cost-focus",
      messages: [{ role: "user", content: "Hello!" }],
  });

  // Fastest time to first token
  const fast = await client.chat.completions.create({
      model: "claude-sonnet-4-20250514:ttft",
      messages: [{ role: "user", content: "Hello!" }],
  });
  ```
</CodeGroup>

Suffixes work with any HTTP client:

```bash theme={null}
curl https://api.auriko.ai/v1/chat/completions \
  -H "Authorization: Bearer $AURIKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o:cost-focus",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

The router parses suffixes only when the model ID contains exactly one colon. Fine-tuned models with multiple colons (for example, `ft:gpt-4o:org:custom`) pass through unchanged.

## Route across models

Pass `gateway.models` instead of `model` to route across multiple models (mutually exclusive with `model`, max 10):

<CodeGroup>
  ```python Python OpenAI theme={null}
  response = client.chat.completions.create(
      model="",
      messages=[{"role": "user", "content": "Hello!"}],
      extra_body={"gateway": {
          "models": ["gpt-4o", "claude-sonnet-4-20250514", "gemini-flash-latest"],
          "routing": {"mode": "pool"}
      }}
  )
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: {
          models: ["gpt-4o", "claude-sonnet-4-20250514", "gemini-flash-latest"],
          routing: { mode: "pool" },
      },
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  import os
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/v1"
  )

  # Pool mode (default): best provider across all models
  response = client.chat.completions.create(
      messages=[{"role": "user", "content": "Hello!"}],
      gateway={"models": ["gpt-4o", "claude-sonnet-4-20250514", "gemini-flash-latest"], "routing": {"mode": "pool"}}
  )

  # Fallback mode: try models in order
  response = client.chat.completions.create(
      messages=[{"role": "user", "content": "Hello!"}],
      gateway={"models": ["gpt-4o", "claude-sonnet-4-20250514"], "routing": {"mode": "fallback"}}
  )
  ```

  ```typescript TypeScript Auriko theme={null}
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/v1",
  });

  // Pool mode (default): best provider across all models
  const response = await client.chat.completions.create({
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { models: ["gpt-4o", "claude-sonnet-4-20250514", "gemini-flash-latest"], routing: { mode: "pool" } },
  });

  // Fallback mode: try models in order
  const fallback = await client.chat.completions.create({
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { models: ["gpt-4o", "claude-sonnet-4-20250514"], routing: { mode: "fallback" } },
  });
  ```

  ```bash cURL theme={null}
  # Pool mode (default): best provider across all models
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "messages": [{"role": "user", "content": "Hello!"}],
      "gateway": {"models": ["gpt-4o", "claude-sonnet-4-20250514", "gemini-flash-latest"], "routing": {"mode": "pool"}}
    }'

  # Fallback mode: try models in order
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "messages": [{"role": "user", "content": "Hello!"}],
      "gateway": {"models": ["gpt-4o", "claude-sonnet-4-20250514"], "routing": {"mode": "fallback"}}
    }'
  ```
</CodeGroup>

| Mode             | Behavior                                                                |
| ---------------- | ----------------------------------------------------------------------- |
| `pool` (default) | Select the best-scoring provider across all requested models            |
| `fallback`       | Try all providers for the first model, then the second model, and so on |

## Set quality constraints

Filter providers by performance requirements. Pass constraint ceilings under `gateway.routing`:

| Field                | Type    | Description                                 |
| -------------------- | ------- | ------------------------------------------- |
| `max_cost_per_1m`    | number  | Maximum cost per 1 million tokens (USD)     |
| `max_ttft_ms`        | integer | Maximum time to first token in milliseconds |
| `min_throughput_tps` | number  | Minimum throughput in tokens per second     |

<CodeGroup>
  ```python Python OpenAI theme={null}
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      extra_body={"gateway": {"routing": {
          "optimize": "balanced",
          "min_throughput_tps": 30,
          "weights": {"cost": 0.6, "ttft": 0.4}
      }}}
  )
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: {
          optimize: "balanced",
          min_throughput_tps: 30,
          weights: { cost: 0.6, ttft: 0.4 },
      } },
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      gateway={"routing": {
          "optimize": "balanced",
          "min_throughput_tps": 30,
          "weights": {"cost": 0.6, "ttft": 0.4}
      }}
  )
  ```

  ```typescript TypeScript Auriko theme={null}
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: {
          optimize: "balanced",
          min_throughput_tps: 30,
          weights: { cost: 0.6, ttft: 0.4 },
      } },
  });
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Hello!"}],
      "gateway": {"routing": {"optimize": "balanced", "min_throughput_tps": 30, "weights": {"cost": 0.6, "ttft": 0.4}}}
    }'
  ```
</CodeGroup>

Constraint ceilings (`max_ttft_ms`, `min_throughput_tps`, `max_cost_per_1m`) evaluate against median (p50) metrics. To rank providers by worst-case (p95) TTFT or throughput for scoring, set `ttft_percentile` or `throughput_percentile` — see [Choose metric percentile](#choose-metric-percentile).

## Filter by parameter support

Not all providers support every optional parameter. By default, Auriko drops unsupported parameters and adds a warning to the response.

Set `require_parameters` to `true` to only route to providers that accept the optional parameters you sent:

<CodeGroup>
  ```python Python OpenAI theme={null}
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      seed=42,
      extra_body={"gateway": {"routing": {
          "optimize": "cost",
          "require_parameters": True,
      }}}
  )
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-5.4",
      messages: [{ role: "user", content: "Hello!" }],
      top_p: 0.9,
      gateway: { routing: {
          optimize: "cost",
          require_parameters: true,
      } },
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      seed=42,
      gateway={
          "routing": {
              "optimize": "cost",
              "require_parameters": True,
          },
      }
  )
  ```

  ```typescript TypeScript Auriko theme={null}
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      seed: 42,
      gateway: {
          routing: {
              optimize: "cost",
              require_parameters: true,
          },
      },
  });
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Hello!"}],
      "seed": 42,
      "gateway": {"routing": {"optimize": "cost", "require_parameters": true}}
    }'
  ```
</CodeGroup>

The following parameters have per-provider support. When you set `require_parameters` to `true`, Auriko checks that your provider supports each one you sent: `temperature`, `top_p`, `seed`, `logit_bias`, `logprobs`, `top_logprobs`, `n`, `presence_penalty`, `frequency_penalty`, `user`, `parallel_tool_calls`, `web_search_options`, `verbosity`, `prompt_cache_key`, `safety_identifier`.

`require_parameters` composes with other constraints. A provider must pass all filters to be eligible. You can check which parameters each provider supports via the model directory endpoint, where each provider entry includes `accepted_params` and `supported_parameters` fields.

<Caution>
  Providers without parameter support data are excluded when `require_parameters` is `true`. This is fail-closed by design.
</Caution>

## Set custom weights

You can override preset strategies with custom weights across three dimensions.

| Dimension  | Field        | What it controls                |
| ---------- | ------------ | ------------------------------- |
| Cost       | `cost`       | Favor lower-cost providers      |
| Latency    | `ttft`       | Favor lower time-to-first-token |
| Throughput | `throughput` | Favor higher tokens-per-second  |

Pass `routing.weights` with your desired dimensions:

<CodeGroup>
  ```python Python OpenAI theme={null}
  # Only cost matters
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      extra_body={"gateway": {"routing": {"weights": {"cost": 1}}}}
  )

  # Mostly cost, some latency
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      extra_body={"gateway": {"routing": {"weights": {"cost": 0.7, "ttft": 0.3}}}}
  )

  # All three dimensions
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      extra_body={"gateway": {"routing": {"weights": {"cost": 0.85, "ttft": 0.5, "throughput": 0.5}}}}
  )
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  // Only cost matters
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: { weights: { cost: 1 } } },
  });

  // Mostly cost, some latency
  const response2 = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: { weights: { cost: 0.7, ttft: 0.3 } } },
  });

  // All three dimensions
  const response3 = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: { weights: { cost: 0.85, ttft: 0.5, throughput: 0.5 } } },
  });

  console.log(response3.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  # Only cost matters
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      gateway={"routing": {"weights": {"cost": 1}}}
  )

  # Mostly cost, some latency
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      gateway={"routing": {"weights": {"cost": 0.7, "ttft": 0.3}}}
  )

  # All three dimensions
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      gateway={"routing": {
          "weights": {
              "cost": 0.85,
              "ttft": 0.5,
              "throughput": 0.5
          }
      }}
  )
  ```

  ```typescript TypeScript Auriko theme={null}
  // Only cost matters
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: { weights: { cost: 1 } } },
  });

  // Mostly cost, some latency
  const response2 = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: { weights: { cost: 0.7, ttft: 0.3 } } },
  });

  // All three dimensions
  const response3 = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: {
          weights: {
              cost: 0.85,
              ttft: 0.5,
              throughput: 0.5,
          },
      } },
  });
  ```

  ```bash curl theme={null}
  # Only cost matters
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Hello!"}],
      "gateway": {"routing": {"weights": {"cost": 1}}}
    }'

  # Mostly cost, some latency
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Hello!"}],
      "gateway": {"routing": {"weights": {"cost": 0.7, "ttft": 0.3}}}
    }'

  # All three dimensions
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Hello!"}],
      "gateway": {"routing": {
        "weights": {
          "cost": 0.85,
          "ttft": 0.5,
          "throughput": 0.5
        }
      }}
    }'
  ```
</CodeGroup>

* The server accepts any non-negative numbers and normalizes them proportionally.
* Omitted dimensions default to 0.
* At least one dimension must be greater than 0.
* `weights` overrides the `optimize` preset, and the response metadata contains `routing_strategy: "custom"`.
* To score using worst-case metrics, set `ttft_percentile` and/or `throughput_percentile` to `"p95"`. See [Choose metric percentile](#choose-metric-percentile).

Providers approaching their rate limits are automatically deprioritized.

## Choose metric percentile

By default, Auriko scores providers using median (p50) metrics. You can switch to 95th-percentile (worst-case) independently for TTFT and throughput:

| Field                   | Controls                                             | Default |
| ----------------------- | ---------------------------------------------------- | ------- |
| `ttft_percentile`       | TTFT **scoring** (which providers rank higher)       | `p50`   |
| `throughput_percentile` | Throughput **scoring** (which providers rank higher) | `p50`   |

Both scoring fields accept `"p50"` (median) or `"p95"` (worst-case). They work with presets and custom weights — no `weights` required.

Example — rank providers by worst-case (p95) TTFT instead of median:

<CodeGroup>
  ```python Python OpenAI theme={null}
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      extra_body={"gateway": {"routing": {
          "optimize": "ttft",
          "ttft_percentile": "p95"
      }}}
  )
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: {
          optimize: "ttft",
          ttft_percentile: "p95",
      } },
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      gateway={"routing": {
          "optimize": "ttft",
          "ttft_percentile": "p95"
      }}
  )
  ```

  ```typescript TypeScript Auriko theme={null}
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: {
          optimize: "ttft",
          ttft_percentile: "p95",
      } },
  });
  ```

  ```bash curl theme={null}
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Hello!"}],
      "gateway": {"routing": {
        "optimize": "ttft",
        "ttft_percentile": "p95"
      }}
    }'
  ```
</CodeGroup>

## Data policy

Control how providers handle your data:

Auriko doesn't store prompts or responses. Set `data_policy: "zdr"` to route only to providers that satisfy zero data retention.

| Policy           | Description                             |
| ---------------- | --------------------------------------- |
| `none` (default) | No restrictions                         |
| `no_training`    | Provider must not use data for training |
| `zdr`            | Zero data retention — strictest policy  |

The hierarchy is `zdr` > `no_training` > `none`. When a per-request policy intersects with an account-level policy, the most restrictive one wins.

<CodeGroup>
  ```python Python OpenAI theme={null}
  response = client.chat.completions.create(
      model="claude-sonnet-4-6",
      messages=[{"role": "user", "content": "Sensitive financial data..."}],
      extra_body={"gateway": {"routing": {"data_policy": "zdr"}}}
  )
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: { data_policy: "zdr" } },
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  response = client.chat.completions.create(
      model="claude-sonnet-4-6",
      messages=[{"role": "user", "content": "Sensitive financial data..."}],
      gateway={"routing": {"data_policy": "zdr"}}
  )
  ```

  ```typescript TypeScript Auriko theme={null}
  const response = await client.chat.completions.create({
      model: "claude-sonnet-4-6",
      messages: [{ role: "user", content: "Sensitive financial data..." }],
      gateway: { routing: { data_policy: "zdr" } },
  });
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-sonnet-4-6",
      "messages": [{"role": "user", "content": "Sensitive financial data..."}],
      "gateway": {"routing": {"data_policy": "zdr"}}
    }'
  ```
</CodeGroup>

## Opt in to premium tiers

Premium-tier offerings are excluded from routing by default. Set `tier` to opt in:

| Value             | Effect                                                       |
| ----------------- | ------------------------------------------------------------ |
| `"priority"`      | Includes Anthropic Fast Mode offerings (2.5x speed, 6x cost) |
| omitted (default) | Excludes premium-tier offerings                              |

<CodeGroup>
  ```python Python OpenAI theme={null}
  response = client.chat.completions.create(
      model="claude-opus-4-6",
      messages=[{"role": "user", "content": "Hello!"}],
      extra_body={"gateway": {"routing": {"tier": "priority"}}}
  )
  ```

  ```typescript TypeScript OpenAI theme={null}
  const response = await client.chat.completions.create({
      model: "claude-opus-4-6",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: { tier: "priority" } },
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  response = client.chat.completions.create(
      model="claude-opus-4-6",
      messages=[{"role": "user", "content": "Hello!"}],
      gateway={"routing": {"tier": "priority"}}
  )
  ```

  ```typescript TypeScript Auriko theme={null}
  const response = await client.chat.completions.create({
      model: "claude-opus-4-6",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: { tier: "priority" } },
  });
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-opus-4-6",
      "messages": [{"role": "user", "content": "Hello!"}],
      "gateway": {"routing": {"tier": "priority"}}
    }'
  ```
</CodeGroup>

Auriko's "priority" tier refers to Anthropic Fast Mode, not Anthropic's separate Priority Tier (committed capacity SLA). See [Routing options](/guides/routing-options#opt-in-to-premium-tiers) for details.

## Provider alias normalization

Provider names in `providers` and `exclude_providers` are case-insensitive and support aliases:

| Alias                                       | Canonical name     |
| ------------------------------------------- | ------------------ |
| `google`, `google_ai`, `googleai`, `gemini` | `google_ai_studio` |
| `fireworks`                                 | `fireworks_ai`     |
| `together`                                  | `together_ai`      |

Unrecognized names pass through as-is (lowercased).

## Configure fallbacks

By default, Auriko retries with alternative providers on 429 (rate limit), 5xx (server error), and timeout responses.

| Setting                 | Default                                         | Description                                                                                                                                                                       |
| ----------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allow_fallbacks`       | `true`                                          | Enable automatic fallback to alternative providers                                                                                                                                |
| `max_fallback_attempts` | 19                                              | Safety ceiling on fallback attempts beyond the primary, range 1-19 (chain length 20 total)                                                                                        |
| `timeout_ms`            | `120000` (streaming) / `300000` (non-streaming) | Per-attempt timeout in milliseconds. For streaming: time to first byte. For non-streaming: time to complete response                                                              |
| `deadline_ms`           | None (streaming) / `1080000` (non-streaming)    | Hard wall-clock cap across all fallback attempts. Non-streaming requests default to 18 minutes; streaming has no default (connections are long-lived). Set explicitly to override |

You can configure per-attempt timeouts with `timeout_ms`. To set a hard wall-clock cap across all fallback attempts, use `deadline_ms`. Non-streaming requests have an 18-minute default deadline; streaming requests have no deadline (opt-in only). If the deadline is exceeded, the request fails with a timeout error.

<CodeGroup>
  ```python Python OpenAI theme={null}
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      extra_body={"gateway": {"routing": {
          "allow_fallbacks": True,
          "max_fallback_attempts": 5
      }}}
  )
  ```

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: {
          allow_fallbacks: true,
          max_fallback_attempts: 5,
      } },
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Auriko theme={null}
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      gateway={"routing": {
          "allow_fallbacks": True,
          "max_fallback_attempts": 5
      }}
  )
  ```

  ```typescript TypeScript Auriko theme={null}
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: {
          allow_fallbacks: true,
          max_fallback_attempts: 5,
      } },
  });
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Hello!"}],
      "gateway": {"routing": {"allow_fallbacks": true, "max_fallback_attempts": 5}}
    }'
  ```
</CodeGroup>