Guides
Each model resolves through a waterfall: an ordered list of provider routes. The gateway serves the highest route you enable that can take the request, so one slug reaches the model across providers and you control the order.
A model's slug does not point at one provider. It points at a waterfall, an ordered list of routes (called rungs). Each rung is one way to reach the model: an Experiential-hosted route paid with platform credits, a route on your own provider key, or your own local endpoint. On a model's page the waterfall shows these rungs top to bottom, in the order the gateway tries them.
Every rung has a Use toggle, which splits the list into two bands:
You reorder the on band by dragging a rung by its handle. That order is your organization's fallback chain, saved as you drag. A BYOK rung also has a Make default action that moves it to the top in one step. At least one rung must stay on, so the last on rung cannot be turned off until you turn another on.
The order is your preference. The gateway serves the request on the highest on rung it can use. An operational failure on that rung (an authentication, transport, or provider error) can move the request down to the next on rung. A rung whose BYOK connection is unhealthy is dropped until it recovers, and a rung your provider policy bars is skipped for the first route your policy allows. Off rungs are never used.
The kind of rung that serves decides who pays:
If every on rung is a BYOK rung and none can serve, the request fails closed and the error names the connection that could not serve. Add a house rung or a second key if you want a route beyond a single account.
Prompt caching lets a provider reuse a prefix it has already seen, so the repeated part of your context is billed at a cheaper cached input rate instead of the full input rate. This is a property of the route, not a switch you flip: some routes publish a cached input rate and some do not. The waterfall and the provider table mark a route that has one with a cache tag and show its Cached $/M price.
There is no per-rung cache toggle. When a route supports prompt caching, the gateway uses it automatically for the eligible prefix; a route with no cached rate simply bills every input token at its normal rate. Because caching is per route, the same model can be cheaper on repeated context through one rung than through another, which is one more reason to order your rungs deliberately. How a cached charge appears on your bill is covered in Credits & billing.
On a model's page, Add a way offers three options. The first two add a rung to thismodel's waterfall, and the new rung lands in the off band so you can place it before you turn it on. The third, Add a local model, is different: it does not add a rung here, it creates a separate model private to your organization.
| Way | What it does | Plan |
|---|---|---|
| Add an API key | Serve the model on your own provider account (BYOK). Your provider bills you directly. | Any plan |
| Serve it yourself | Route the model through your own endpoint (a reseller or proxy), in the model's own format. | Pro |
| Add a local model | Register an OpenAI-compatible server your organization runs as a private model. | Pro |
The step-by-step for each path, the fields every provider needs, and the API shapes are in Adding models.
A model covered by a free promotion shows a Free tier rung pinned above the chain: the same Experiential-hosted route, priced Free. It serves from a daily free allowance and is display-only, so it has no Use toggle and no drag handle.
Below it sits the Past the free limit control. Off (the default), requests stop once the free allowance is spent. Turning it on spends your platform credits past the limit, and it applies to every free model at once. Enabling it yourself needs a card on file and the settled $1 verification; an admin flips it for the whole organization. See Credits & billing for credits, spend limits, and auto-recharge.
Models covers the catalog, the two payment lanes, and the waterfall API (GET / PUT /api/models/<slug>/waterfall). Adding models walks each way to add a rung in detail.