Benchmark routing

Benchmark routing lets you select a benchmark alias instead of pinning one model. Router uses the alias's weighted model mix to choose a strong route for the workload while balancing quality and cost.

The aliases available to an API key appear alongside concrete models in GET /v1/models, with "owned_by": "router" and a router_alias object. Use the returned alias ID as the request's model; do not hardcode an alias that is not in the key's catalog.

{
  "model": "your-benchmark-alias",
  "input": "Resolve this software issue and explain the change."
}

Weighted aliases

Each benchmark alias represents multiple models and their configured weights. Router samples from that mix for each request, so traffic follows the current benchmark results without requiring application changes when the mix is updated.

Candidates and context windows

An alias's router_alias metadata in GET /v1/models lists the candidate models the alias currently routes between, in the order fallback tries them, each with its own limits. Because those models can have different context windows, the alias-level limits are the floor across every candidate:

{
  "id": "your-benchmark-alias",
  "owned_by": "router",
  "router_alias": {
    "schema_version": 1,
    "name": "your-benchmark-alias",
    "limits": { "context_window": 260000, "max_output_tokens": 64000 },
    "candidates": [
      {
        "model": "anthropic:claude-fable-5",
        "provider": "anthropic",
        "provider_model": "claude-fable-5",
        "limits": { "context_window": 260000, "max_output_tokens": 64000 }
      },
      {
        "model": "openai:gpt-5.4",
        "provider": "openai",
        "provider_model": "gpt-5.4",
        "limits": { "context_window": 1050000, "max_output_tokens": 128000 }
      }
    ]
  }
}

When a client needs one number for prompt budgeting or a compaction threshold, use the alias-level limits.context_window: it holds whichever candidate a request routes to. The same floor is repeated in the row's standard router metadata block, so a client that only reads router.limits works unchanged. The candidate mix follows current benchmark results, so re-read the catalog rather than caching these numbers long-term.

An alias appears only while every candidate states a context window and max output tokens; max_input_tokens is null when any candidate leaves it unstated. Pricing is omitted on alias rows because each request can route to a model with different rates.

Automatic fallback

If the selected model is unavailable or fails before a response starts, Router automatically tries another model in the alias. The fallback remains within the alias, so callers keep the same stable model ID.

For explicit, application-controlled ordering instead, send a models list as described in Add fallbacks.