Realtime TTS-2 is live. Built for realtime conversation that feels human. Read the Realtime TTS-2 announcement

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
json
{
  "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 messages array from the request body. On the Responses API, messages holds the request's input
Routes are evaluated in order, and the first route whose condition evaluates to true is selected.

The table below lists the available operations for constructing a CEL expression:

OperationExampleDescription
Equalitytier == "premium"Matches a specific value.
Comparisonrequest_count > 100Numeric comparisons (>, <, >=, <=).
Logical ANDtier == "premium" && region == "us-east"Both conditions must be true.
Logical ORtier == "premium" || tier == "enterprise"Either condition must be true.
Range checkscore >= 80 && score <= 100Matches 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() > 10Gets 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() > 3Number 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:

LimitValue
Time for all the conditions a request evaluates100 ms
Evaluation cost of a condition, in CEL cost units2,000,000
Values on each side of an ==, != or in comparison10,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() or messages.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.

bash
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:

json
{
  "cel_expression": "subscription_tier == \"pro\""
}

Geographic Routing

Route requests based on user location:

json
{
  "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:

json
{
  "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:

json
{
  "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:

json
{
  "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:

json
{
  "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.