Handle a model quota wall

A coding model has a ceiling: a subscription window, a monthly API quota, a credit balance, a premium-request allowance. When a task’s pinned model hits that ceiling, the run fails through no fault of the work.

SupaCloud handles that in two steps, and the split between them is the whole point:

• Same class → automatic. The task continues on an equivalent model of the same class (for example another flagship model, possibly from a different provider). No one has to do anything.
• Different class → your decision. If every model of that class is out too, SupaCloud does not quietly continue on something weaker. It parks the task on an approval gate and asks you.

Caution

A class change is never automatic and never expires into one. An unanswered tier-change gate waits indefinitely; the task stays blocked rather than being silently degraded.

The model classes

Class	What it is
flagship	Top-end reasoning models.
balanced	The everyday workhorse class.
fast	Cheap, low-latency models.
independent_review	A deliberately different-provider reviewer. It is a role, not a strength rung, so it has no weaker class to drop to.

Each class holds an ordered, provider-spanning chain of models. On a quota wall SupaCloud walks that chain in order and takes the first model that is genuinely usable right now — meaning your workspace has a credential for its provider, that credential still has quota headroom, and the provider’s circuit breaker is closed.

What you see when it happens

1. A line in the live feed. “Quota reached on claude-fable-5 — continuing on gpt-5.6-sol (same flagship class)”. The same line reaches your linked Telegram or Discord chat while you are following the task.

2. An audit entry. Every decision — a switch, a gate, an exhausted class, a spent cap — is recorded under Reports → Audit with the models involved.

3. A routing note. For a backlog-dispatched task the switch is also written to the routing decision log on the operations view.

When it asks you

The approval appears in your normal Approvals inbox (web, approvals in the web terminal, /approvals in Telegram or Discord) as a model class change gate:

Model class ‘flagship’ is exhausted (claude-fable-5 hit its quota and every equivalent model of that class is out of quota or unavailable). Fall back to the weaker ‘balanced’ class for this task? Rejecting leaves the task blocked on its own class.

• Approve — the task relaunches on the first usable model of the weaker class, within about a minute.
• Reject — the task stays where it is. Nothing is downgraded.

Note

A coordinator agent cannot answer this gate for you. Agents may answer only open-question gates; a class change is deliberately in a class they cannot decide.

Tip

To decide between the two, you usually want to know when the wall comes down. Open Reports → Usage: the exhausted window’s row carries its own reset countdown, so rejecting and waiting is a decision you can price. A rolling 5-hour window that filled at 14:00 is free again at 19:00 — the countdown states that rather than leaving you to guess, and the card tells you how fresh the reading is.

Limits that stop a runaway

• At most two automatic same-class switches per task. After that the same approval gate appears instead of a third switch.
• No ping-pong. A model the task has already run on is never offered again.
• One decision per run. A crash-recovered run cannot switch the same task twice.
• Unknown model → no guess. If the pinned model is not listed in any class chain, SupaCloud makes no assumption about its class and does not fall back; the task fails as it would have before. Add the model to your workspace chain to enable the fallback.

Change the chains for your workspace

The built-in chains are a sensible default, not a policy. A workspace owner or admin can replace any class’s chain — for example to prefer your own provider order, or to add a model the default does not know.

In the app

1. Open Settings → Models and scroll to Model fallback chains. The card shows the chains this workspace actually resolves right now — your override where you set one, the built-in chain everywhere else.

2. Expand a class (Flagship, Balanced, Fast, Independent second opinion — the independent_review class in the table above) to see its ordered candidates. Order is preference order: the first usable entry wins.

3. Per row, pick the harness, type the provider-native model id and optionally pin an effort (leave it on Keep the task’s effort to inherit the task’s own setting). Use the arrows to reorder and ✕ to remove.

4. Save. Only the classes you actually touched are written — a class you did not open keeps whatever it resolves today, including future built-in updates. Reset to built-in clears the whole workspace override in one step.

A member sees the same card read-only.

Note

Removing every row of a class and saving is meaningful: it switches the automatic fallback off for that class, so a quota wall there goes straight to the approval gate.

Carrier order

Right below the chains sits the Carrier order card. It decides how the calibration (see Let the evidence propose the order below) arranges a class’s chain across carriers:

• Subscriptions first, API keys as the last resort (the default): every model your workspace reaches through a connected subscription with measured headroom (a Google, OpenAI or Anthropic subscription) ranks ahead of every model it reaches only through an API key such as OpenRouter. Within each group the score decides. A subscription is paid for anyway, so a run on it costs nothing extra, while an API-key call is billed every time.
• By score only, carrier ignored: the score alone orders the chain; a paid model may sit ahead of a subscription model.

The pick is saved at once and the next calibration run applies it. It does not change which route a single model is dispatched on: a subscription route with room already wins that choice on its own.

Through the API

The same override is one PATCH /api/workspaces/{id}/settings field:

{
  "model_fallback_chains": {
    "flagship": [
      { "agent": "codex", "model": "gpt-5.6-sol" },
      { "agent": "claude", "model": "claude-fable-5" }
    ]
  }
}

A class you do not name keeps its built-in chain; an empty array switches the automatic fallback off for that class; "model_fallback_chains": null clears the override entirely. Malformed input is rejected with a 400 — nothing is half-saved. The read side of the same endpoint returns both your raw override (model_fallback_chains) and the resolved result the runtime uses (model_fallback_chains_effective).

A narrower override: one agent profile

An agent profile can carry its own chains under retry_policy.model_fallback.chains (same shape), layered on top of the workspace chains for tasks that run on that profile. Edit it in Settings → Agent profiles → Raw.

Related

• Approve agent actions
• Track usage and budget
• Set the autonomy level

Let the evidence propose the order

Deciding the order by hand means keeping a benchmark board, a price list and your own run history in your head at once. SupaCloud can do that reading for you and propose an order — as a proposal, never as a change.

Ask for a proposal

1. In Settings → Models → Model fallback chains, use Calibrate from evidence. SupaCloud reads the model catalog (prices, lifecycle), the public benchmark boards and this workspace’s own run telemetry, and computes a proposed order. The external sources are not called live: a background refresh fetches them a few times a day into a snapshot, and the preview shows each snapshot’s age. Refresh now (admins, rate-limited) fetches on demand — a new ranking still needs a new calibrate run afterwards.

2. The preview plays the reordering: the list opens in your current order and settles into the proposed one, so you can see what moves rather than compare two lists. Use Play again to watch it once more.

3. Every movement states its reason and the numbers behind it, each with its source and the date of that measurement — not the date of the run. A movement that claims a measurement and cites none is marked on its own row and counted in the header; treat those as the lines to read hardest.

4. Apply to the chains writes the proposal. Discard records that you said no and changes nothing.

Note

Reopening the preview shows the run you already read, never a fresh one. Recomputing on open would mean deciding about a diff you had not seen.

Caution

If you edit the chains by hand between asking for a proposal and applying it, applying is refused and the chains stay as you left them — the proposal argues about a state that no longer exists. Ask for a fresh one.

Which route a price comes from, and when a cheaper one wins

The same model is often sold twice: directly by the vendor, and resold through a router such as OpenRouter, each with its own rate. SupaCloud ranks and dispatches on the price of the route your workspace would actually use — the cheapest one you hold a credential for, reseller surcharge included — not on the vendor’s own list price. The proposal line names the route the figure came from, so a number that looks wrong under the vendor’s own pricing page usually is not.

A cheaper route does not automatically take the model. It has to be cheaper by at least 15 % before it displaces the route your chain already uses. That is the same threshold that decides whether a model is worth swapping, so there is one rule to remember rather than two:

• Gemini 3.7 Flash at 3.75 direct against 1.875 resold saves 50 % — it switches.
• A route that is 5 % cheaper moves nothing.
• Exactly 15 % switches.
• The rule holds in both directions: a chain already running on a router is not pulled back to the vendor by a 5 % advantage either.

This is not discount detection

The threshold does not know whether a price is a promotion. No provider publishes when a price ends, and SupaCloud does not guess — it never claims a price is temporary.

What the threshold does is make being wrong cheap: a small, short-lived advantage never moves a chain in the first place, so there is nothing to move back when it disappears. A large advantage still switches, and will switch back when it ends. If you need a route pinned regardless of price, set the chain by hand — the calibration only ever proposes.

When the evidence is not enough to rank

A price alone does not order models. When a run finds no quality and no speed measurement at all — every benchmark source down or unconfigured, no usable telemetry — the preview says so instead of proposing a price-sorted list: the current chains stay as they are, and only models that are unreachable, non-compliant, unable to call tools or vendor-retired are removed. Repair the sources named in the preview, refresh, and calibrate again. A movement that is carried only by its price is labelled price-backed only on its row.

A quality floor is judged only on its own scale

The fast class carries a quality floor: a model whose intelligence reading sits below it, or that has no such reading, takes no slot there whatever its price. A benchmark index is versioned by its publisher, and a new version moves every model’s number at once — so the floor names the scale it was set on, and a reading on another scale (or one that carries no scale label at all) is not judged: the class keeps its current chain, and the preview names both scales. Set the floor’s value and its scale together to arm it again. A model that leaves a chain because of the floor shows its reading and the floor on its row — it is never reported as rescored. A model beaten on both price and quality by another is dropped only from the classes that other model can actually enter; where the floor refuses the cheaper one, the dearer one keeps its slot.

Some figures stay inside your instance

A number carrying an instance only marker comes from a source whose licence permits internal use but not redistribution. You may read it; do not paste it outside your instance.

Letting it apply itself

A workspace at autonomy Autonomous or above lets a daily pass apply a proposal without asking — but only a plain reordering, and only when nothing objects:

• adding a model the chain never held, or dropping one, always waits for you;
• a movement without evidence stops the pass;
• a source that did not answer that day stops the pass, because the ranking then stood on less than it should;
• the operator’s global dispatch switch stops it, like everything else that acts on its own.

Every unattended outcome is written to the audit log — including the passes that changed nothing, with the reason. Under Autonomous, calibration still runs when you press the button; only the automatic applying is off.