Routing
Conditional routing
Route requests based on CEL expressions and request metadata
Conditional routing sends requests to different models based on conditions you set on request metadata.
You can use conditional routing to:
- Segment by user tier — route premium users to flagship models and free users to cost-effective ones.
- Route by geography — direct requests to different models based on geography.
- Optimize by complexity — send simple prompts to fast, cheap models and complex ones to high-capability models.
Basic Structure
Routes are defined directly on the Router. Each route has a route object and a condition object.
Example router set up
{
"name": "routers/my-router",
"routes": [
{
"route": {
"route_id": "premium-tier",
"variants": [
{
"variant": {
"variant_id": "premium-gpt5",
"model_id": "openai/gpt-5.2"
},
"weight": 100
}
]
},
"condition": {
"cel_expression": "tier == \"premium\""
}
},
{
"route": {
"route_id": "free-tier",
"variants": [
{
"variant": {
"variant_id": "free-flash",
"model_id": "google-ai-studio/gemini-2.5-flash"
},
"weight": 100
}
]
},
"condition": {
"cel_expression": "tier == \"free\""
}
}
],
"defaultRoute": {
"route_id": "default",
"variants": [
{
"variant": {
"variant_id": "default-variant",
"model_id": "google-ai-studio/gemini-2.5-flash"
},
"weight": 100
}
]
}
}The condition field accepts a CEL expression that can be evaluated against the following from each Chat Completions or Responses request:
- Request metadata — key-value pairs sent in
extra_body.metadata(e.g. user tier, region, complexity score). - Messages — the full
messagesarray from the request body. On the Responses API,messagesholds the request'sinput
true is selected.The table below lists the available operations for constructing a CEL expression:
| Operation | Example | Description |
|---|---|---|
| Equality | tier == "premium" | Matches a specific value. |
| Comparison | request_count > 100 | Numeric comparisons (>, <, >=, <=). |
| Logical AND | tier == "premium" && region == "us-east" | Both conditions must be true. |
| Logical OR | tier == "premium" || tier == "enterprise" | Either condition must be true. |
| Range check | score >= 80 && score <= 100 | Matches values within a range. |
startsWith() | user_id.startsWith("enterprise-") | Checks if a string starts with a prefix. |
endsWith() | user_id.endsWith("-admin") | Checks if a string ends with a suffix. |
contains() | user_id.contains("test") | Checks if a string contains a substring. |
matches() | messages.last().content.matches("(?i).*\\bcode\\b.*") | RE2 regex match on any string field. |
size() | user_id.size() > 10 | Gets the length of a string. |
messages.has() | messages.has() | true if the message array exists and is non-empty. |
messages.first() | messages.first().content.contains("system") | First message in the array. |
messages.last() | messages.last().content.matches("(?i).*help.*") | Last message in the array. |
messages.get(i) | messages.get(0).role == "system" | Message at index i (0-based). |
messages.len() | messages.len() > 3 | Number of messages in the array. |
messages.all() | messages.all(m, m.role == "user") | true if the check passes for every message. |
Expressions are typed — ensure your metadata types match. Use count == 100 when the value is a number and tier == "premium" when it's a string. Mismatched types will not match.
Condition limits
The router evaluates your conditions on every request, so each request has these limits:
| Limit | Value |
|---|---|
| Time for all the conditions a request evaluates | 100 ms |
| Evaluation cost of a condition, in CEL cost units | 2,000,000 |
Values on each side of an ==, != or in comparison | 10,000 |
Saving a router doesn't check these limits, because the cost depends on each request. A condition can pass on a short conversation and fail on a long one.
A request that goes over a limit fails with 400 and type: "invalid_request_error". The router doesn't skip the route, use defaultRoute or try a fallback, and no model is called. On the Responses API, the error also has param: "model". The message names the condition and the reason. Retrying doesn't help: change the condition.
To stay within the limits:
- Avoid nested loops over messages, such as
messages.all(a, messages.all(b, ...)). The work multiplies with each level and grows with the conversation. - Read one message with
messages.last(),messages.first()ormessages.get(i)instead of looping over all of them. - Put a cheap check first when you need a loop. In
messages.len() < 10 && messages.all(m, m.role == "user"), the loop doesn't run on longer conversations. - Test the condition with the longest conversation you expect to send.
Making a Request
Pass the values your conditions need in extra_body.metadata when you call your router.
curl --request POST \
--url https://api.inworld.ai/v1/chat/completions \
--header 'Authorization: Basic <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"model": "inworld/my-router",
"messages": [
{"role": "user", "content": "Hello"}
],
"extra_body": {
"metadata": {
"tier": "premium",
"user_id": "user-123",
"region": "us-east"
}
}
}'In this example, CEL expressions can use tier, user_id, and region to match a route and select its model configuration.
Example Use Cases
User Subscription Tiers
Route users to different models based on their subscription tier:
{
"cel_expression": "subscription_tier == \"pro\""
}Geographic Routing
Route requests based on user location:
{
"cel_expression": "region == \"eu\""
}Prompt-Based Routing
Combine fast regex checks on the prompt with metadata checks in one condition. This lets you route by both what the user is asking and who the user is.
Route coding questions from premium users to a reasoning model:
{
"cel_expression": "messages.last().content.matches(\"(?i).*\\\\b(code|debug|refactor|bug fix)\\\\b.*\") && tier == \"premium\""
}Regex also works on metadata fields (e.g. user_id.matches(".*-admin$")) and on any message — use messages.first() to match the first message or messages.get(i) for a specific turn.
Route translation requests to a multilingual model:
{
"cel_expression": "messages.last().content.matches(\"(?i).*\\\\btranslat(e|ion)\\\\b.*\")"
}Route long conversations (e.g. 10+ turns) to a model with a large context window:
{
"cel_expression": "messages.len() > 10"
}Conditions are evaluated before route variants are selected, so messages defined inside variants are not part of condition evaluation.
Dynamic Tiering
Route requests to different model tiers based on prompt complexity. Use a lightweight classifier in your application to score complexity, then let the router pick the right model:
{
"routes": [
{
"route": {
"route_id": "complex",
"variants": [
{
"variant": { "variant_id": "gpt5-premium", "model_id": "openai/gpt-5.2" },
"weight": 100
}
]
},
"condition": {
"cel_expression": "complexity_score >= 8"
}
},
{
"route": {
"route_id": "standard",
"variants": [
{
"variant": { "variant_id": "gpt5", "model_id": "openai/gpt-5-mini" },
"weight": 100
}
]
},
"condition": {
"cel_expression": "complexity_score >= 4"
}
}
],
"defaultRoute": {
"route_id": "simple",
"variants": [
{
"variant": { "variant_id": "flash", "model_id": "openai/gpt-5-nano" },
"weight": 100
}
]
}
}Simple tasks go to fast, cheap models while complex tasks get flagship models — optimizing cost without sacrificing quality where it matters.