GATEWAY & INTEGRATION

LLM routing and fallback

Route each LLM request by cost, speed or reliability, with bounded fallback to another supplier route for the same model. Set a mode per account, key or request.

THE SHORT ANSWER

Tokely routes every request for a model across its configured supplier routes. Choose Balanced, Lowest cost, Fastest, Most reliable or Fixed per account, per API key or per request with the X-Tokely-Routing header. If an eligible route fails before work is accepted, the gateway retries another route for the same model.

Connect in one request

curl https://api.tokely.me/v1/chat/completions \
  -H "Authorization: Bearer $TOKELY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Tokely-Routing: lowest-cost" \
  -d '{"model": "claude-sonnet-5",
       "messages": [{"role": "user", "content": "Hello"}],
       "max_tokens": 256}'

# OpenRouter-style shortcuts also work:
#   "model": "claude-sonnet-5:floor"     (lowest cost)
#   "model": "claude-sonnet-5:nitro"     (fastest)
#   "provider": {"sort": "price"}

Base URL https://api.tokely.me/v1. Create a key in the dashboard and keep it in an environment variable. Quickstart · Model IDs and endpoints

Five routing modes

Balanced weighs price and observed health. Lowest cost compares current route quotes for a normalized token mix. Fastest and Most reliable use measured latency and success; with too little data they fall back to Balanced. Fixed keeps the selected route and fails instead of switching. The mode never changes the model you asked for.

Account, key or request

Set a default in account settings, override it for a single API key, or send X-Tokely-Routing on one request. OpenRouter-style model suffixes (:floor, :nitro, :stable) and provider.sort are accepted, so an existing integration keeps its routing intent when it switches base URL.

Fallback that does not double-charge

Retries happen only for eligible failures before the supplier accepts the work. Partial streams are not replayed, accepted media tasks stay pinned to their supplier, and timeouts that may already have produced output do not trigger a second paid generation. Some models have a single route; redundancy is not promised for every model.

See what happened

Every response returns an X-Request-ID. The matching dashboard log shows each attempt, its outcome and duration, the routing mode and the final status, without exposing supplier credentials or internal channel names.

Questions before you switch

What is LLM routing?

LLM routing chooses which supplier route serves a request for a given model, based on price, latency, reliability or a fixed preference, and falls back when a route fails. Tokely does this inside its hosted gateway.

Does routing change the model?

No. Routing selects among routes for the same model ID. Switching to a different model is always your explicit choice.

Is fallback available for every model?

No. Fallback needs at least two compatible routes. Model pages and request logs show the routes actually used.

START WITH YOUR OWN WORKLOAD

Know the price.
Then make the call.

Check the model, compare the rate, and connect with a Tokely key.