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

# Get router

> Get a router configuration by router ID.


## API reference

**Endpoint:** `GET https://api.inworld.ai/router/v1/routers/{router_id}`

### Authorization

- `Authorization` (string; required) — Your [authentication](../../../api-reference/introduction) credentials. For Basic authentication, please populate `Basic $INWORLD_API_KEY`.
  
  A standard API key can call chat completions, the Responses and Messages APIs, moderation and Decisions. To create, update or delete routers, the key also needs [write permissions for the Router API](https://docs.inworld.ai/portal/api-keys.md#key-permissions). You can create a key in one command with the [Inworld CLI](../../../developer-tools/inworld-cli): `inworld workspace add-key`.

### Path parameters

- `router_id` (string; required) — Router ID.

### Response

Status: `200`. Content type: `application/json`.

- `name` (string; required) — Unique ID of router. Cannot be edited after creation. Send it as `my-router` or `routers/my-router`; both create the same router. The ID uses lowercase letters, digits, `-` and `_`, up to 61 characters.
  
  Used to call this router in the [Chat Completions](https://docs.inworld.ai/api-reference/routerAPI/chat-completions.md) API by setting the `model` parameter to `inworld/<router-name>`.
- `displayName` (string) — Router display name.
- `routes` (object[]) — List of conditional routes evaluated in order. Routes are checked sequentially, and the first route whose CEL condition evaluates to `true` is selected. Within the selected route, a variant is chosen based on weights (which must sum to 100 within that route).
  - `route` (object; required) — Route configuration containing route ID and variants.
    - `route_id` (string; required) — Unique identifier for this route (must be unique within the router).
    - `variants` (object[]; required) — Weighted variants within this route. When this route is selected (based on its CEL condition), a variant is chosen based on weights. **Weights must sum to exactly 100 within this route** - they are not normalized and are independent of weights in other routes.
      - `variant` (object; required) — A variant within a route specifying the model to use.
        - `variant_id` (string; required) — Unique identifier for this variant (must be unique within the route).
        - `model_id` (string) — The model to use, which can be:
          - A model id (e.g., `deepseek-v4-flash`). The best provider is [automatically selected](https://docs.inworld.ai/router/capabilities/provider-routing.md) by latency, or you can control provider selection via `model_selection.provider`. See [Models](https://docs.inworld.ai/api-reference/modelsAPI/modelservice/list-models.md) for available models.
          - A provider-prefixed model id (e.g., `openai/gpt-5.4` or `groq/openai/gpt-oss-120b`). This specifies the provider and model to use. A model hosted by Inworld is written `inworld/<name>` here.
          - `auto` for automatic model selection based on criteria like price, latency, or intelligence
          
          See [Model ids](https://docs.inworld.ai/router/capabilities/request-level.md#model-ids).
        - `model_selection` (object) — Configuration for model selection behavior: For specific model_id, defines fallback models if primary fails. For model_id "auto", defines candidate models and selection criteria.
          - `models` (string[]) — Optional list of model IDs for fallback or candidate selection. Behavior depends on model_id in the route: When model_id names a model (e.g., "openai/gpt-4o" or "deepseek-v4-flash"): fallback models to try on failure. When model_id is "auto": candidate models to select from (or all available if not specified).
          - `sort` (object[]) — Optional composite sorting criteria. Must be an array of SortCriteria objects with `metric` field (e.g., [{"metric": "SORT_METRIC_PRICE"}, {"metric": "SORT_METRIC_LATENCY"}]). String arrays like ["price", "latency"] are NOT supported in router configuration.
            - `metric` (enum<string>; required; default: "SORT_METRIC_UNSPECIFIED"; options: "SORT_METRIC_UNSPECIFIED", "SORT_METRIC_PRICE", "SORT_METRIC_LATENCY", "SORT_METRIC_THROUGHPUT", "SORT_METRIC_INTELLIGENCE", "SORT_METRIC_MATH", "SORT_METRIC_CODING") — Sort metric for model selection.
            - `direction` (enum<string>; default: "SORT_DIRECTION_UNSPECIFIED"; options: "SORT_DIRECTION_UNSPECIFIED", "SORT_DIRECTION_ASCENDING", "SORT_DIRECTION_DESCENDING") — Sort direction for ordering.
          - `ignore` (string[]) — Optional list of model IDs or providers to exclude from selection. Specific model: "google-ai-studio/gemini-2.5-pro". Entire provider: "openai". A `provider/model` set as `model_id` is never excluded. Without `models`, and with any `model_id` but `auto`, `ignore` also adds every other catalog model it doesn't exclude as a fallback. See [Use only one provider](https://docs.inworld.ai/router/capabilities/provider-routing.md#use-only-one-provider).
          - `provider` (object) — Provider routing configuration. Use when `model_id` is specified without a provider prefix (e.g., `deepseek-v4-flash`) to control which providers are tried and in what order.
            - `order` (string[]) — Explicit list of providers to try, in order. Example: ["deepseek", "inworld"]. When specified, providers are tried in this exact order (`sort` criteria will be ignored), and providers not in the list are not used.
            - `allow_fallbacks` (boolean; default: true) — Whether to allow falling back to the next provider if the current one fails. Defaults to true.
        - `text_generation_config` (object) — Text generation parameters (temperature, max_tokens, etc.) for this variant. If set, this entire text generation configuration will be used instead of any default text generation configuration specified.
          
          For example, suppose the default text generation configuration is {max_tokens: 100} and the variant sets {temperature: 0.9}. The variant passes only {temperature: 0.9} to the model. It does not set max_tokens to 100.
          - `max_tokens` (integer) — Maximum number of tokens to generate.
          - `top_p` (number) — Top-p for generation.
          - `temperature` (number) — Temperature for generation.
          - `repetition_penalty` (number) — Repetition penalty.
          - `frequency_penalty` (number) — Frequency penalty.
          - `presence_penalty` (number) — Presence penalty.
          - `stop_sequences` (string[]) — Stop sequences.
          - `seed` (integer) — Random seed for generation.
          - `logit_bias` (object[]) — Logit bias for token modification.
            - `token_id` (string; required) — Token ID to apply bias to.
            - `bias_value` (integer; required) — Bias value to apply to the token.
          - `reasoning` (object) — Configuration for reasoning/thinking models (e.g., OpenAI o-series, Claude, Gemini thinking). Controls how models perform chain-of-thought reasoning.
            - `effort` (enum<string>; options: "unspecified", "none", "minimal", "low", "medium", "high", "xhigh") — Controls the reasoning effort level. The server will default to MEDIUM if effort is not specified. NONE disables reasoning entirely. MINIMAL uses ~10% of max completion tokens, LOW ~20%, MEDIUM ~50%, HIGH ~80%, XHIGH ~95%.
            - `max_tokens` (integer) — Maximum number of tokens to use for reasoning. Anthropic/Google-style control. Takes precedence over effort when specified. For providers that only support effort levels, this is converted to the appropriate level.
            - `exclude` (boolean) — Whether to exclude reasoning tokens from the response. When true, the model still uses reasoning internally but doesn't return it. Default is false (reasoning is included in response if available).
        - `message_templates` (object[]) — Message templates for this variant.
          - `role` (string; required) — Message role: `system`, `user`, `assistant` (and `tool` when applicable).
          - `content` (string) — Text content for text-only messages.
          - `content_items` (oneOf[]) — Content items for multimodal messages (text + images). If not empty, this takes precedence over `content`.
          - `tool_calls` (object[]) — Tool calls generated by the model.
            - `id` (string; required) — ID of the tool call.
            - `type` (enum<string>; required; options: "function") — The type of the tool call. Always 'function'.
            - `function` (object; required) — The function that the model called.
              - `name` (string; required) — The name of the function to call.
              - `arguments` (string; required) — The arguments to call the function with, as a JSON string.
          - `tool_call_id` (string) — Tool call ID this message is responding to (for `tool` role).
        - `web_search` (object) — Web search configuration, at the top level or in `extra_body`. With a router-run engine, the model calls a search tool in a loop and the router returns a grounded answer; `native` uses the provider's built-in search. See [Web search](https://docs.inworld.ai/router/capabilities/web-search.md).
          - `engine` (enum<string>; default: "exa"; options: "exa", "brave", "google", "native") — Search backend: `exa`, `brave` or `google`, or `native` for the provider's built-in search.
          - `max_results` (integer; default: 3) — Search results per search call, 1 to 10.
          - `max_steps` (integer; default: 1) — Maximum search rounds before the final answer, 1 to 5.
      - `weight` (number; required) — Proportion of traffic to route to this variant within its route. **Weights must sum to exactly 100 within each route** - they are not normalized. For example, if a route has two variants with weights 70 and 30, they will receive 70% and 30% of traffic respectively. Weights are independent per route - a weight of 70 in one route does not relate to weights in other routes.
  - `condition` (object; required) — A single condition rule to evaluate against the request context.
    - `cel_expression` (string; required) — Common Expression Language (CEL) expression evaluated against request metadata and messages. Routes are evaluated in order, and the first route whose `cel_expression` evaluates to `true` is selected. 
      
      See [Conditional Routing](https://docs.inworld.ai/router/capabilities/conditional-routing.md) for supported operations and additional details.
- `defaultRoute` (object) — Route configuration containing route ID and variants.
  - `route_id` (string; required) — Unique identifier for this route (must be unique within the router).
  - `variants` (object[]; required) — Weighted variants within this route. When this route is selected (based on its CEL condition), a variant is chosen based on weights. **Weights must sum to exactly 100 within this route** - they are not normalized and are independent of weights in other routes.
    - `variant` (object; required) — A variant within a route specifying the model to use.
      - `variant_id` (string; required) — Unique identifier for this variant (must be unique within the route).
      - `model_id` (string) — The model to use, which can be:
        - A model id (e.g., `deepseek-v4-flash`). The best provider is [automatically selected](https://docs.inworld.ai/router/capabilities/provider-routing.md) by latency, or you can control provider selection via `model_selection.provider`. See [Models](https://docs.inworld.ai/api-reference/modelsAPI/modelservice/list-models.md) for available models.
        - A provider-prefixed model id (e.g., `openai/gpt-5.4` or `groq/openai/gpt-oss-120b`). This specifies the provider and model to use. A model hosted by Inworld is written `inworld/<name>` here.
        - `auto` for automatic model selection based on criteria like price, latency, or intelligence
        
        See [Model ids](https://docs.inworld.ai/router/capabilities/request-level.md#model-ids).
      - `model_selection` (object) — Configuration for model selection behavior: For specific model_id, defines fallback models if primary fails. For model_id "auto", defines candidate models and selection criteria.
        - `models` (string[]) — Optional list of model IDs for fallback or candidate selection. Behavior depends on model_id in the route: When model_id names a model (e.g., "openai/gpt-4o" or "deepseek-v4-flash"): fallback models to try on failure. When model_id is "auto": candidate models to select from (or all available if not specified).
        - `sort` (object[]) — Optional composite sorting criteria. Must be an array of SortCriteria objects with `metric` field (e.g., [{"metric": "SORT_METRIC_PRICE"}, {"metric": "SORT_METRIC_LATENCY"}]). String arrays like ["price", "latency"] are NOT supported in router configuration.
          - `metric` (enum<string>; required; default: "SORT_METRIC_UNSPECIFIED"; options: "SORT_METRIC_UNSPECIFIED", "SORT_METRIC_PRICE", "SORT_METRIC_LATENCY", "SORT_METRIC_THROUGHPUT", "SORT_METRIC_INTELLIGENCE", "SORT_METRIC_MATH", "SORT_METRIC_CODING") — Sort metric for model selection.
          - `direction` (enum<string>; default: "SORT_DIRECTION_UNSPECIFIED"; options: "SORT_DIRECTION_UNSPECIFIED", "SORT_DIRECTION_ASCENDING", "SORT_DIRECTION_DESCENDING") — Sort direction for ordering.
        - `ignore` (string[]) — Optional list of model IDs or providers to exclude from selection. Specific model: "google-ai-studio/gemini-2.5-pro". Entire provider: "openai". A `provider/model` set as `model_id` is never excluded. Without `models`, and with any `model_id` but `auto`, `ignore` also adds every other catalog model it doesn't exclude as a fallback. See [Use only one provider](https://docs.inworld.ai/router/capabilities/provider-routing.md#use-only-one-provider).
        - `provider` (object) — Provider routing configuration. Use when `model_id` is specified without a provider prefix (e.g., `deepseek-v4-flash`) to control which providers are tried and in what order.
          - `order` (string[]) — Explicit list of providers to try, in order. Example: ["deepseek", "inworld"]. When specified, providers are tried in this exact order (`sort` criteria will be ignored), and providers not in the list are not used.
          - `allow_fallbacks` (boolean; default: true) — Whether to allow falling back to the next provider if the current one fails. Defaults to true.
      - `text_generation_config` (object) — Text generation parameters (temperature, max_tokens, etc.) for this variant. If set, this entire text generation configuration will be used instead of any default text generation configuration specified.
        
        For example, suppose the default text generation configuration is {max_tokens: 100} and the variant sets {temperature: 0.9}. The variant passes only {temperature: 0.9} to the model. It does not set max_tokens to 100.
        - `max_tokens` (integer) — Maximum number of tokens to generate.
        - `top_p` (number) — Top-p for generation.
        - `temperature` (number) — Temperature for generation.
        - `repetition_penalty` (number) — Repetition penalty.
        - `frequency_penalty` (number) — Frequency penalty.
        - `presence_penalty` (number) — Presence penalty.
        - `stop_sequences` (string[]) — Stop sequences.
        - `seed` (integer) — Random seed for generation.
        - `logit_bias` (object[]) — Logit bias for token modification.
          - `token_id` (string; required) — Token ID to apply bias to.
          - `bias_value` (integer; required) — Bias value to apply to the token.
        - `reasoning` (object) — Configuration for reasoning/thinking models (e.g., OpenAI o-series, Claude, Gemini thinking). Controls how models perform chain-of-thought reasoning.
          - `effort` (enum<string>; options: "unspecified", "none", "minimal", "low", "medium", "high", "xhigh") — Controls the reasoning effort level. The server will default to MEDIUM if effort is not specified. NONE disables reasoning entirely. MINIMAL uses ~10% of max completion tokens, LOW ~20%, MEDIUM ~50%, HIGH ~80%, XHIGH ~95%.
          - `max_tokens` (integer) — Maximum number of tokens to use for reasoning. Anthropic/Google-style control. Takes precedence over effort when specified. For providers that only support effort levels, this is converted to the appropriate level.
          - `exclude` (boolean) — Whether to exclude reasoning tokens from the response. When true, the model still uses reasoning internally but doesn't return it. Default is false (reasoning is included in response if available).
      - `message_templates` (object[]) — Message templates for this variant.
        - `role` (string; required) — Message role: `system`, `user`, `assistant` (and `tool` when applicable).
        - `content` (string) — Text content for text-only messages.
        - `content_items` (oneOf[]) — Content items for multimodal messages (text + images). If not empty, this takes precedence over `content`.
        - `tool_calls` (object[]) — Tool calls generated by the model.
          - `id` (string; required) — ID of the tool call.
          - `type` (enum<string>; required; options: "function") — The type of the tool call. Always 'function'.
          - `function` (object; required) — The function that the model called.
            - `name` (string; required) — The name of the function to call.
            - `arguments` (string; required) — The arguments to call the function with, as a JSON string.
        - `tool_call_id` (string) — Tool call ID this message is responding to (for `tool` role).
      - `web_search` (object) — Web search configuration, at the top level or in `extra_body`. With a router-run engine, the model calls a search tool in a loop and the router returns a grounded answer; `native` uses the provider's built-in search. See [Web search](https://docs.inworld.ai/router/capabilities/web-search.md).
        - `engine` (enum<string>; default: "exa"; options: "exa", "brave", "google", "native") — Search backend: `exa`, `brave` or `google`, or `native` for the provider's built-in search.
        - `max_results` (integer; default: 3) — Search results per search call, 1 to 10.
        - `max_steps` (integer; default: 1) — Maximum search rounds before the final answer, 1 to 5.
    - `weight` (number; required) — Proportion of traffic to route to this variant within its route. **Weights must sum to exactly 100 within each route** - they are not normalized. For example, if a route has two variants with weights 70 and 30, they will receive 70% and 30% of traffic respectively. Weights are independent per route - a weight of 70 in one route does not relate to weights in other routes.
- `defaults` (object) — Configuration defaults for the router.
  - `message_templates` (object[]) — Message templates for the router.
    - `role` (string; required) — Message role: `system`, `user`, `assistant` (and `tool` when applicable).
    - `content` (string) — Text content for text-only messages.
    - `content_items` (oneOf[]) — Content items for multimodal messages (text + images). If not empty, this takes precedence over `content`.
    - `tool_calls` (object[]) — Tool calls generated by the model.
      - `id` (string; required) — ID of the tool call.
      - `type` (enum<string>; required; options: "function") — The type of the tool call. Always 'function'.
      - `function` (object; required) — The function that the model called.
        - `name` (string; required) — The name of the function to call.
        - `arguments` (string; required) — The arguments to call the function with, as a JSON string.
    - `tool_call_id` (string) — Tool call ID this message is responding to (for `tool` role).
  - `text_generation_config` (object) — Text generation configuration that will be applied to all variants that do not text generation configuration specified
    - `max_tokens` (integer) — Maximum number of tokens to generate.
    - `top_p` (number) — Top-p for generation.
    - `temperature` (number) — Temperature for generation.
    - `repetition_penalty` (number) — Repetition penalty.
    - `frequency_penalty` (number) — Frequency penalty.
    - `presence_penalty` (number) — Presence penalty.
    - `stop_sequences` (string[]) — Stop sequences.
    - `seed` (integer) — Random seed for generation.
    - `logit_bias` (object[]) — Logit bias for token modification.
      - `token_id` (string; required) — Token ID to apply bias to.
      - `bias_value` (integer; required) — Bias value to apply to the token.
    - `reasoning` (object) — Configuration for reasoning/thinking models (e.g., OpenAI o-series, Claude, Gemini thinking). Controls how models perform chain-of-thought reasoning.
      - `effort` (enum<string>; options: "unspecified", "none", "minimal", "low", "medium", "high", "xhigh") — Controls the reasoning effort level. The server will default to MEDIUM if effort is not specified. NONE disables reasoning entirely. MINIMAL uses ~10% of max completion tokens, LOW ~20%, MEDIUM ~50%, HIGH ~80%, XHIGH ~95%.
      - `max_tokens` (integer) — Maximum number of tokens to use for reasoning. Anthropic/Google-style control. Takes precedence over effort when specified. For providers that only support effort levels, this is converted to the appropriate level.
      - `exclude` (boolean) — Whether to exclude reasoning tokens from the response. When true, the model still uses reasoning internally but doesn't return it. Default is false (reasoning is included in response if available).

### Response examples

#### 200: default_response

```json
{
  "name": "string",
  "displayName": "string",
  "routes": [
    {
      "route": {
        "route_id": "string",
        "variants": [
          {
            "variant": {},
            "weight": 0
          }
        ]
      },
      "condition": {
        "cel_expression": "string"
      }
    }
  ],
  "defaultRoute": {
    "route_id": "string",
    "variants": [
      {
        "variant": {
          "variant_id": "string",
          "model_id": "string",
          "model_selection": {
            "models": [],
            "sort": [],
            "ignore": [],
            "provider": {}
          },
          "text_generation_config": {
            "max_tokens": 0,
            "top_p": 0,
            "temperature": 0,
            "repetition_penalty": 0,
            "frequency_penalty": 0,
            "presence_penalty": 0,
            "stop_sequences": [],
            "seed": 0,
            "logit_bias": [],
            "reasoning": {}
          },
          "message_templates": [
            {}
          ],
          "web_search": {
            "engine": "exa",
            "max_results": 3,
            "max_steps": 1
          }
        },
        "weight": 0
      }
    ]
  },
  "defaults": {
    "message_templates": [
      {
        "role": "string",
        "content": "string",
        "content_items": [
          {}
        ],
        "tool_calls": [
          {
            "id": "string",
            "type": "function",
            "function": {}
          }
        ],
        "tool_call_id": "string"
      }
    ],
    "text_generation_config": {
      "max_tokens": 0,
      "top_p": 0,
      "temperature": 0,
      "repetition_penalty": 0,
      "frequency_penalty": 0,
      "presence_penalty": 0,
      "stop_sequences": [
        "string"
      ],
      "seed": 0,
      "logit_bias": [
        {
          "token_id": "string",
          "bias_value": 0
        }
      ],
      "reasoning": {
        "effort": "unspecified",
        "max_tokens": 0,
        "exclude": true
      }
    }
  }
}
```

#### 401: default_response

```json
"Unauthorized"
```

### Code examples

#### cURL

```bash
curl --location 'https://api.inworld.ai/router/v1/routers/<router_id>' \
--header "Authorization: Basic $INWORLD_API_KEY"
```

#### Python

```python
import os
import requests

router_id = "<router_id>"
url = f"https://api.inworld.ai/router/v1/routers/{router_id}"
headers = {
    "Authorization": f"Basic {os.getenv('INWORLD_API_KEY')}"
}

response = requests.get(url, headers=headers)
print(response.json())
```

#### JavaScript

```javascript
const routerId = '<router_id>';
const url = `https://api.inworld.ai/router/v1/routers/${routerId}`;

const response = await fetch(url, {
  headers: {
    'Authorization': `Basic ${process.env.INWORLD_API_KEY}`,
  },
});

const data = await response.json();
console.log(data);
```
