---
title: "List routers"
method: GET
path: "/router/v1/routers"
tags: ["Router Management"]
---

# List routers

`GET /router/v1/routers`

List routers available to your API key.

## Query parameters

- `page_size` integer
- `page_token` string

## Response `200`

A successful response.

- ListRoutersResponse
  - `routers` Router[] — The list of routers.
    - `name` string, required — Unique ID of router. Cannot be edited after creation. Used to call this router in the [Chat Completions](/api-reference/routerAPI/chat-completions) API by setting the `model` parameter to `inworld/<router-name>`.
    - `displayName` string — Router display name.
    - `routes` ConditionalRoute[] — 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` Route, required — Route configuration containing route ID and variants.
        - `route_id` string, required — Unique identifier for this route (must be unique within the router).
        - `variants` WeightedVariant[], 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` Variant, 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., `gpt-oss-120b`). The best provider is [automatically selected](/router/usage/specific-model#provider-routing) by latency, or you can control provider selection via `model_selection.provider`. See [Models](/api-reference/modelsAPI/modelservice/list-models) for available models. - A provider-prefixed model id (e.g., `openai/gpt-5`). This specifies the provider and model to use. - `auto` for automatic model selection based on criteria like price, latency, or intelligence
            - `model_selection` ModelSelection — LLM routing configuration for model selection and fallback.
              - …
            - `text_generation_config` TextGenerationConfig — Text generation configuration that will be applied to all variants that do not text generation configuration specified
              - …
            - `message_templates` MessageTemplate[] — Message templates for this variant.
              - …
            - `web_search` WebSearchConfig — Web search configuration (under `extra_body`). The LLM calls a search engine in a tool-calling loop, then synthesizes a grounded answer. See [Web search](/router/capabilities/web-search).
              - …
          - `weight` number, float, 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` Condition, 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](/router/capabilities/conditional-routing) for supported operations and additional details.
    - `defaultRoute` Route — Route configuration containing route ID and variants.
      - `route_id` string, required — Unique identifier for this route (must be unique within the router).
      - `variants` WeightedVariant[], 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` Variant, 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., `gpt-oss-120b`). The best provider is [automatically selected](/router/usage/specific-model#provider-routing) by latency, or you can control provider selection via `model_selection.provider`. See [Models](/api-reference/modelsAPI/modelservice/list-models) for available models. - A provider-prefixed model id (e.g., `openai/gpt-5`). This specifies the provider and model to use. - `auto` for automatic model selection based on criteria like price, latency, or intelligence
          - `model_selection` ModelSelection — LLM routing configuration for model selection and fallback.
            - `models` string[] — Optional list of model IDs for fallback or candidate selection. Behavior depends on model_id in the route: When model_id has provider (e.g., "openai/gpt-4o"): fallback models to try on failure. When model_id is "auto": candidate models to select from (or all available if not specified).
            - `sort` SortCriteria[] — 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.
              - …
            - `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".
            - `provider` ProviderConfig — Configuration for provider-level routing when using a model without a provider prefix.
              - …
          - `text_generation_config` TextGenerationConfig — 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, float — Top-p for generation.
            - `temperature` number, float — Temperature for generation.
            - `repetition_penalty` number, float — Repetition penalty.
            - `frequency_penalty` number, float — Frequency penalty.
            - `presence_penalty` number, float — Presence penalty.
            - `stop_sequences` string[] — Stop sequences.
            - `seed` integer — Random seed for generation.
            - `logit_bias` LogitBias[] — Logit bias for token modification.
              - …
            - `reasoning` ReasoningConfig — Reasoning configuration for models that support chain-of-thought reasoning. Provides a unified interface across different providers (OpenAI, Anthropic, Google, Groq, etc.).
              - …
          - `message_templates` MessageTemplate[] — 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` ContentItem[] — Content items for multimodal messages (text + images). If not empty, this takes precedence over `content`.
              - …
            - `tool_calls` ToolCall[] — Tool calls generated by the model.
              - …
            - `tool_call_id` string — Tool call ID this message is responding to (for `tool` role).
          - `web_search` WebSearchConfig — Web search configuration (under `extra_body`). The LLM calls a search engine in a tool-calling loop, then synthesizes a grounded answer. See [Web search](/router/capabilities/web-search).
            - `engine` 'exa' | 'google' — Search backend. Valid values are `exa` and `google`.
            - `max_results` integer — Search results per search call.
            - `max_steps` integer — Maximum search/refine rounds.
        - `weight` number, float, 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` RouterDefaults — Configuration defaults for the router.
      - `message_templates` MessageTemplate[] — 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` ContentItem[] — Content items for multimodal messages (text + images). If not empty, this takes precedence over `content`.
          - union — Deprecated. Use ContentPart instead.
            - object
              - …
            - object
              - …
        - `tool_calls` ToolCall[] — Tool calls generated by the model.
          - `id` string, required — ID of the tool call.
          - `type` 'function', required — 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` TextGenerationConfig — 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, float — Top-p for generation.
        - `temperature` number, float — Temperature for generation.
        - `repetition_penalty` number, float — Repetition penalty.
        - `frequency_penalty` number, float — Frequency penalty.
        - `presence_penalty` number, float — Presence penalty.
        - `stop_sequences` string[] — Stop sequences.
        - `seed` integer — Random seed for generation.
        - `logit_bias` LogitBias[] — 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` ReasoningConfig — Reasoning configuration for models that support chain-of-thought reasoning. Provides a unified interface across different providers (OpenAI, Anthropic, Google, Groq, etc.).
          - `effort` '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).
  - `next_page_token` string — A token to retrieve the next page of results.

## Other responses

- `401` — Unauthorized - Invalid or missing API key

---

[API](https://skmtc.net/inworld/apis/inworld-text-to-speech-api.md) · [All operations](https://skmtc.net/inworld/apis/inworld-text-to-speech-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/inworld/inworld-text-to-speech-api/versions/e79009799a0d/schema)