Skip to main content
← All use cases
API reference

​
The scenario

Every reason call costs credits, and the cost difference between the cheapest and the most expensive model in the catalog is more than a hundredfold. Most spaces do not need the expensive one; one or two do. What this recipe shows that no other does: reading the model catalog and pinning a model per space, so cost follows importance instead of being one global setting.

​
Step 1 — See what you can actually use

GET /v1/models answers in OpenAI’s list shape, so the entries are under data — that is deliberate, because a stock OpenAI client’s models.list() hits this same path. The catalog is generated and checked in, not fetched live, so pricing is reproducible — a price change arrives as a reviewed release, never as a surprise on your bill. Aliases exist for the common cases: fast, balanced. Naming an alias means “whatever we currently think is the sensible default at that tier” — at the moment you name it. The catalog grows as models are added, so count it from GET /v1/models rather than from any number on this page.

​
Step 2 — Pin one to a space

model and depth are both required, and that is on purpose: this PUT is a full replace, so a call naming only the model clears the depth. Pass both every time. To change one, read the pair back with get_reason_settings first.

​
Step 3 — Check what a space is actually on

null means the space is on the deployment default — which is the right answer for most spaces, and worth confirming before you debug a cost you did not expect. An alias does not read back as an alias. model="fast" is resolved when you set it and the space stores the model id it resolved to (today something like us.amazon.nova-lite-v1:0), so get_reason_settings shows the id. That also means a space set to fast stays on that model when the alias later moves — re-set it to follow.

​
Step 4 — Undo it

Resetting is better than pinning to today’s default by name: a space pinned to an explicit id keeps that model forever, including after we move the default to something better and cheaper.

​
Evals

  1. Ask the same question of one space on fast and on balanced.
  2. Compare the answers side by side, not in isolation — the cheap model is often indistinguishable on factual recall and noticeably worse on synthesis.
  3. Check get_usage()["credits_used"] before and after to see the real credit difference.
  4. Pick per space based on that, not on the model’s reputation.

​
Guardrails

A pinned model is pinned forever. It will not follow the platform default forward, so a space pinned today is still on today’s model in a year. Reset rather than re-pin unless you have a reason to freeze it.
  • Reason settings are owner-only. A read-only member of a shared space cannot change what it thinks with.
  • This is reason only. The drop-in proxy’s model is chosen per call or via chat settings; they are separate knobs.
  • An unknown model id is a 400, not a fallback. That is deliberate — silently answering with a different model than you asked for would corrupt any comparison you were trying to make.

​
Where to go next

Cut the bill without cutting recall — the other half of the cost story, which is how much context you send rather than which model reads it.