list
GET /v1/models. The window filter answers “what could I run in this window?”; search matches free text against the id and the name. Hundreds of models are catalogued, so page it — limit defaults to 20 and caps at 100.
Each entry:
string
The model id you pass as
model on agents.create.integer
Native context size in tokens.
integer
The longest reply this model may produce, and what the pre-flight quote is bounded by.
Window[]
The window configurations this model can serve.
("low" | "medium" | "high")[]
The effort levels this model accepts.
retrieve
GET /v1/models/{id}. One entry, for the id you already hold — checking what an agent’s pinned model can do without paging the catalogue to find it. An id this deploy does not serve is a not_found error, so this is also how you validate one before you run it.
autoSelect
POST /v1/models/auto_select. An optional add-on — a choice over ids you name, given the conversation so far (Model auto-selection is the capability in full). The answer is one of your options keys, meant to be handed straight to the next call in the same program as model: proxy.messages, or an agent’s or session’s model. It selects and stops; it does not call the model it picked, and it changes nothing about routing or vetta/auto.
{ options, min_confidence } policy can also ride on the call itself as model_selection — on proxy.messages / proxy.completions per call, or on an agent per turn — so the router runs the pick and the model in one step. autoSelect is for when you want the id in hand first — see letting the call pick for itself.
string
One of the
options keys.number | null
The selector’s probability for its own choice;
null when it reported no distribution.Record<string, number> | null
The full distribution over the
options keys, or null.boolean
true only when default was returned in place of the selector’s pick.number
What this call debited, in integer micro-USD — what the ledger actually took.
{ input_tokens: number }
The input tokens the selection consumed, or the pre-flight estimate when none were reported.
default applies only under min_confidence: when the selector’s confidence for its pick is null or below the threshold, model is default and defaulted is true, with confidence and probabilities still reporting what it said. min_confidence without default is a validation_failed on min_confidence.
It fails closed. A deploy with no selector is feature_not_configured; an unreachable selector is rate_limited or internal_error, as the proxy reports an upstream failure; an answer outside your options is internal_error. Each is the same VettaError every other method throws, with the same codes, and none of them is debited — default is a confidence policy, not an outage policy, so catch the error if you want to fall back on one.
It is an organization-level call billed as input tokens: the conversation is estimated first and the balance must cover the quote (else insufficient_credits), then one debit with one input line item lands under the request id, readable through credits.ledger. spent_micro_usd on the reply is that amount. Every validation rule — exact catalogue ids only, 2–16 options, 1–32 turns and 32000 characters in all, nothing truncated for you — is spelled out on the API page.
vetta/auto is in the catalogue like any other id, and picks the model per request. It serves the
immediate window only, and is quoted against a price ceiling then billed at the rate of the model
that answered — see Vetta Auto.