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 that is not already first also carries a one-click control that makes it the default (moves it to the top). 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.
Adding a key replaces the platform lane for that provider by default.With no custom order, your OpenAI key takes the place of the platform's OpenAI rung at the same position: requests that would have used platform credits on OpenAI use your key instead, and the platform's OpenAI rung is not dialled. The waterfall shows your key where the replaced rung was, with the replaced platform rung in the off band. To use your key only as a fallback, turn the platform rung on and drag your key below it — that order becomes your organization's chain for the model.
A BYOK key can also carry fallback rules: the failures it is a fallback for. The rules are per key, and you set them on a rung that sits belowthe first. A key with fallback rules never replaces the platform lane and is never dialled first, so it reaches a route only through a Waterfall that places it below another rung: setting a rule from a model page writes the displayed order as that model's chain first, and a rule on a key that no Waterfall places below a rung is refused with that instruction. On a model where no chain names such a key, the key is off until you turn it on. An active restriction remains visible even if you move the key first: reordering does not clear its account-wide rule or make it eligible for a first dial. The waterfall shows a small fallback-rules icon to the left of its Use toggle; open it to inspect or deliberately change which failures dial this key. By default every failure is selected, so the key is a fallback wherever you place it. Deselect down to a subset — say only the cybersecurity-policy refusal — and its rungs are never dialled first: they are used only after a prior rung failed with one of the selected failures, and every other failure moves on to the next unrestricted rung instead. The rule follows the key, so it applies to that account's rung on every model whose Waterfall places it.
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 organization or per-rung cache toggle. A cached price describes how reported cache reads are billed; it does not guarantee cache support or a hit. Some providers cache automatically, while Claude routes can require explicit cache checkpoints. Support depends on the exact upstream adapter, model, prefix length, and expiry. Inspect the response usage and ignored-parameter disclosures to verify that your route honors your cache controls. Cache writes can cost more than ordinary input. Falling back to another provider can lose a warm cache. 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.