> ## 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.

# Routing and Extensions

> Use multi-model routing, routing options, and provider extensions with the Response API

Auriko's `gateway` and `extensions` parameters use identical structure in Chat Completions and the Response API. Pass them at the top level of the request body.

## 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`)

## Route across models

Route a request across multiple models:

<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.responses.create(
      input="What is the capital of France?",
      extra_body={
          "gateway": {
              "models": ["gpt-4o", "claude-sonnet-4-20250514"],
              "routing": {"optimize": "cost"}
          }
      }
  )

  print(response.output_text)
  ```

  ```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.responses.create({
      input: "What is the capital of France?",
      // @ts-expect-error Auriko extension
      gateway: {
          models: ["gpt-4o", "claude-sonnet-4-20250514"],
          routing: { optimize: "cost" },
      },
  });

  console.log(response.output_text);
  ```

  ```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"
  )

  response = client.responses.create(
      input="What is the capital of France?",
      gateway={
          "models": ["gpt-4o", "claude-sonnet-4-20250514"],
          "routing": {"optimize": "cost"}
      }
  )

  print(response.output_text)
  print(f"Provider: {response.routing_metadata.provider}")
  print(f"Cost: ${response.routing_metadata.cost.usd}")
  ```

  ```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",
  });

  const response = await client.responses.create({
      input: "What is the capital of France?",
      gateway: {
          models: ["gpt-4o", "claude-sonnet-4-20250514"],
          routing: { optimize: "cost" },
      },
  });

  console.log(response.output_text);
  console.log(`Provider: ${response.routing_metadata?.provider}`);
  console.log(`Cost: $${response.routing_metadata?.cost?.usd}`);
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/responses \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": "What is the capital of France?",
      "gateway": {
        "models": ["gpt-4o", "claude-sonnet-4-20250514"],
        "routing": {"optimize": "cost"}
      }
    }'
  ```
</CodeGroup>

## Set routing options

Control routing strategy with `gateway.routing`:

<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.responses.create(
      input="Summarize the benefits of solar energy",
      extra_body={
          "gateway": {
              "models": ["gpt-4o", "claude-sonnet-4-20250514", "gemini-2.5-flash"],
              "routing": {
                  "optimize": "cost",
                  "max_cost_per_1m": 5.0,
                  "max_ttft_ms": 2000
              }
          }
      }
  )

  print(response.output_text)
  ```

  ```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.responses.create({
      input: "Summarize the benefits of solar energy",
      // @ts-expect-error Auriko extension
      gateway: {
          models: ["gpt-4o", "claude-sonnet-4-20250514", "gemini-2.5-flash"],
          routing: {
              optimize: "cost",
              max_cost_per_1m: 5.0,
              max_ttft_ms: 2000,
          },
      },
  });

  console.log(response.output_text);
  ```

  ```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"
  )

  response = client.responses.create(
      input="Summarize the benefits of solar energy",
      gateway={
          "models": ["gpt-4o", "claude-sonnet-4-20250514", "gemini-2.5-flash"],
          "routing": {
              "optimize": "cost",
              "max_cost_per_1m": 5.0,
              "max_ttft_ms": 2000
          }
      }
  )

  print(response.output_text)
  ```

  ```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",
  });

  const response = await client.responses.create({
      input: "Summarize the benefits of solar energy",
      gateway: {
          models: ["gpt-4o", "claude-sonnet-4-20250514", "gemini-2.5-flash"],
          routing: {
              optimize: "cost",
              max_cost_per_1m: 5.0,
              max_ttft_ms: 2000,
          },
      },
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/responses \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "input": "Summarize the benefits of solar energy",
      "gateway": {
        "models": ["gpt-4o", "claude-sonnet-4-20250514", "gemini-2.5-flash"],
        "routing": {
          "optimize": "cost",
          "max_cost_per_1m": 5.0,
          "max_ttft_ms": 2000
        }
      }
    }'
  ```
</CodeGroup>

See [Routing Options](/guides/routing-options) for all strategies and [Advanced Routing](/guides/advanced-routing) for constraint combinations.

## Pass provider extensions

Pass provider-specific parameters with `extensions`:

<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.responses.create(
      model="claude-sonnet-4-20250514",
      input="Write a haiku about programming",
      extra_body={
          "extensions": {
              "anthropic": {
                  "metadata": {"user_id": "user-123"}
              }
          }
      }
  )

  print(response.output_text)
  ```

  ```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.responses.create({
      model: "claude-sonnet-4-20250514",
      input: "Write a haiku about programming",
      // @ts-expect-error Auriko extension
      extensions: {
          anthropic: {
              metadata: { user_id: "user-123" },
          },
      },
  });

  console.log(response.output_text);
  ```

  ```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"
  )

  response = client.responses.create(
      model="claude-sonnet-4-20250514",
      input="Write a haiku about programming",
      extensions={
          "anthropic": {
              "metadata": {"user_id": "user-123"}
          }
      }
  )

  print(response.output_text)
  ```

  ```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",
  });

  const response = await client.responses.create({
      model: "claude-sonnet-4-20250514",
      input: "Write a haiku about programming",
      extensions: {
          anthropic: {
              metadata: { user_id: "user-123" },
          },
      },
  });

  console.log(response.output_text);
  ```

  ```bash cURL theme={null}
  curl https://api.auriko.ai/v1/responses \
    -H "Authorization: Bearer $AURIKO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "claude-sonnet-4-20250514",
      "input": "Write a haiku about programming",
      "extensions": {
        "anthropic": {
          "metadata": {"user_id": "user-123"}
        }
      }
    }'
  ```
</CodeGroup>

See [Extensions and Thinking](/guides/extensions-and-thinking#use-provider-passthrough) for all provider extension fields.

## Access routing metadata

Every Auriko response includes routing metadata with provider, cost, and latency details.

With the Auriko SDK ([Python](/sdk/python), [TypeScript](/sdk/typescript)):

<CodeGroup>
  ```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"
  )

  response = client.responses.create(
      model="gpt-4o",
      input="Hello!"
  )

  meta = response.routing_metadata
  print(f"Provider: {meta.provider}")
  print(f"Model: {meta.provider_model_id}")
  print(f"Strategy: {meta.routing_strategy}")
  print(f"TTFT: {meta.ttft_ms}ms")
  print(f"Throughput: {meta.throughput_tps} tps")
  if meta.cost:
      print(f"Cost: ${meta.cost.usd}")
  ```

  ```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",
  });

  const response = await client.responses.create({
      model: "gpt-4o",
      input: "Hello!",
  });

  const meta = response.routing_metadata;
  console.log(`Provider: ${meta?.provider}`);
  console.log(`Model: ${meta?.provider_model_id}`);
  console.log(`Strategy: ${meta?.routing_strategy}`);
  console.log(`TTFT: ${meta?.ttft_ms}ms`);
  console.log(`Throughput: ${meta?.throughput_tps} tps`);
  console.log(`Cost: $${meta?.cost?.usd}`);
  ```
</CodeGroup>

For routing metadata with the OpenAI SDK, see [OpenAI Compatibility](/openai-compatibility#access-routing-metadata).

For streaming, access routing metadata from the completed response:

<CodeGroup>
  ```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"
  )

  stream = client.responses.create(
      model="gpt-4o",
      input="Hello!",
      stream=True
  )

  for event in stream:
      if event.type == "response.output_text.delta":
          print(event.delta, end="", flush=True)

  meta = stream.completed_response.routing_metadata
  print(f"\nProvider: {meta.provider}, Cost: ${meta.cost.usd}")
  ```

  ```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",
  });

  const stream = await client.responses.create({
      model: "gpt-4o",
      input: "Hello!",
      stream: true,
  });

  for await (const event of stream) {
      if (event.type === "response.output_text.delta") {
          process.stdout.write(event.delta);
      }
  }

  const meta = stream.completedResponse?.routing_metadata;
  console.log(`\nProvider: ${meta?.provider}, Cost: $${meta?.cost?.usd}`);
  ```
</CodeGroup>

For routing metadata with the OpenAI SDK, see [OpenAI Compatibility](/openai-compatibility#access-routing-metadata).

Fields: `provider`, `provider_model_id`, `model_canonical`, `routing_strategy`, `ttft_ms`, `throughput_tps`, `cost.usd`.

See [Routing Options](/guides/routing-options), [Advanced Routing](/guides/advanced-routing), [Response Metadata](/contract/response-metadata), and [Response Headers](/contract/response-headers) for details.