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

# Routing Rules

> Use CEL-based routing rules to redirect AI Gateway requests to different models based on request attributes, evaluated in priority order.

Routing Rules are CEL-based conditions that intercept requests to the [**AI Gateway**](/docs/ai-gateway/using-the-router.md) and redirect them to a different model when matched. Rules are evaluated in priority order and the first matching rule wins. No further rules are evaluated after a match.

## Use cases

Routing rules are most useful when traffic needs to be redirected or distributed at the gateway level based on request attributes, without modifying any calling application.

> [accordion] Swap the model for a support bot without changing any code
>
> Intercepts support bot requests addressed to one model and silently redirects them to a cheaper one, so the calling application needs no changes to benefit from the cost saving.

> [accordion] Send simple and complex documents to different models
>
> Two rules at the same priority split document traffic by complexity: simple documents go to a lighter model, complex ones go to a more capable model, all based on metadata attached to each request.

> [accordion] Keep file attachment requests on models that support them
>
> Matches requests that include a file attachment and routes them through an ordered list of models that all support native file input, so the request succeeds even if the first model is unavailable.

> [accordion] Automatically reroute traffic when a provider goes down
>
> A low-priority catch-all rule that redirects traffic to an alternative set of models whenever primary providers are unavailable, keeping requests flowing without manual intervention.

> [accordion] Spread load evenly across multiple endpoints for the same model
>
> Distributes requests in round-robin mode across multiple endpoints serving the same model, balancing inference load across providers without any changes required on the caller side.

## How routing rules work

When a request arrives at the AI Gateway, the **AI Gateway** evaluates all active routing rules in ascending priority order. The first rule whose CEL expression matches the request determines the target model. If no rule matches, the model from the original request payload is used.

**Example:** A request arrives with `model: "openai/gpt-5.6-sol"`. A routing rule with condition `model.contains("gpt-5.6-sol")` and target `openai/gpt-5.4-mini` is the highest-priority matching rule. The **AI Gateway** redirects the request to `gpt-5.4-mini`, regardless of what the caller specified. In CEL expressions, `model` refers to the model value from the request payload.

> [card] [See also: Request-level load balancing](/docs/ai-gateway/features/load-balancing.md)
>
> To distribute traffic across providers at the request level without organization-wide rules, use the `load_balancer` parameter directly in your API calls.

## Visibility

* Visible to workspace administrators only.

## Creating a routing rule

From the **Routing Rules** list, click <kbd> Routing Rule</kbd>. The form opens as a full page with a back control and an unsaved-changes confirmation. It carries five sections, and the submit button reads **Create Rule**, or **Save Changes** once the rule exists.

### General

| Field | Description |
| - | - |
| **Rule name** | A descriptive name for this routing rule. |
| **Description** | Optional context for administrators. |
| **Priority** | A numeric value that sets the evaluation order for this rule. Rules are evaluated in ascending order: priority `0` is evaluated before priority `10`. The first matching rule wins. |
| **Enable rule** | Disabled rules remain saved but are not evaluated for requests. |

### Load Balancer

Optional. Defines the target model or models to route matching requests to. Leave this section empty to build a rule that exists only to apply a [plugin](#plugins) or a [cache](#cache) to matched traffic, with no model routing at all.

**Load balancing strategy** sets how the targets are used:

* **Fallback**: Route to the primary model. Try the next model when it fails with status `408`, `429`, `500`, `502`, `503`, `504`, or `529` by default. Once the rule has a target model, **Fallback status codes** appears and overrides this list; leave it empty to use the default. The API field is `models_config.fallback_on_codes`, accepting up to 20 unique integers from 400 through 599. This field is available only in Fallback mode.
* **Latency**: Route to the model with the lowest recently observed latency. See [Latency-based routing](/docs/ai-gateway/features/load-balancing.md#latency-based-routing) for the full selection algorithm.
* **Weighted**: Split traffic across models by percentage weights.
* **Round Robin**: Rotate evenly across all configured models.

Choose **Latency** when minimizing response time matters more than a fixed traffic split. Choose **Weighted** or **Round Robin** when the split itself, such as cost control or A/B testing, is the goal.

Click <kbd> Models</kbd> to add a target model. The menu groups models by provider.

Each target has a remove control. **Fallback** also gives each target a drag handle for reordering, and **Weighted** adds a **Traffic weight** slider to set that model's share, which must add up to 100%.

> [!WARNING]
>
> When a request matches this routing rule, its **Load Balancer** configuration completely replaces the request's own `model`, `load_balancer`, `fallbacks`, and `fallback_on_codes` values; they are never merged. A request-level [`load_balancer`](/docs/ai-gateway/features/load-balancing) parameter has no effect once a matching routing rule with configured models applies.

### Cache

Optional. Give the rule its own response cache for matching requests. Exact-match requests reuse a cached response instead of hitting a model. Leaving this section disabled adds no cache of its own, so matched requests keep using their request-level [`cache`](/docs/ai-gateway/features/cache) setting.

Set **Enable cache** to turn the cache on, then choose **Time to live** to control how long matching responses stay cached, from 5 minutes up to 3 days. The default is 1 hour.

When a rule has cache enabled, a matching request uses the rule's cache configuration instead of the request's own [`cache`](/docs/ai-gateway/features/cache) parameter; the two are not merged. See [LLM response cache](/docs/ai-gateway/features/cache.md) for how caching works.

### Plugins

Optional. Attach plugins that run on traffic matching this rule. Plugins can transform the request, the response, or stored traces.

Click <kbd> Plugin</kbd> to attach one of the following:

| Plugin | What it does |
| - | - |
| **PII Redaction** | Replaces personally identifiable information with placeholders before the provider sees it, then restores the original values in the response. Configure the entities to mask, the detection threshold, and the failure behavior. See [PII Redaction](/docs/ai-gateway/features/plugins/pii-redaction.md). |
| **Response Healing** | Repairs malformed JSON in model output before the response reaches the caller. Takes no configuration. See [Response Healing](/docs/ai-gateway/features/plugins/response-healing.md). |
| **Trace Scrubbing** | Masks request and response fields in stored traces for matched traffic. Configure which fields to scrub. See [Trace Scrubbing](/docs/ai-gateway/features/plugins/trace-scrubbing.md). |

### Conditions

Define when this routing rule should apply to a request. The **Rule Builder** builds the CEL expression shown read-only in the **CEL Expression Preview**; leaving it empty applies the rule to every request.

Select **Add rule** to choose a condition type:

| Condition | Description |
| - | - |
| **Header** | Match on a request header name and value. |
| **Model** | Match on the model specified in the request payload. |
| **Identity** | Match on the identity making the request. |
| **Metadata** | Match on metadata attached to the request. |
| **Project** | Match on the project scope of the request. |

Each **Add rule** creates a condition group titled **Rule 1 · N conditions**. Inside a group, select **Condition** to add another condition, and <kbd /> to remove one. Drag a condition by its handle to reorder it. Conditions in a group are joined with `and` by default; select the **AND** pill between two conditions to switch the group to `or`. **Delete** removes the whole group.

Rule groups are joined with `or` by default; select the pill between two groups to switch them to `and`.

## Editing and deleting a routing rule

Click a rule's name in the **Routing Rules** list to open it in the same form. An existing rule exposes **Delete Rule** in the form footer, next to **Save Changes**. Deleting asks for confirmation first.

The list's row actions menu offers **Edit**, **Enable** or **Disable**, and **Delete**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.