Models

There is no fixed list of models. The catalogue is read from the inference network and cached briefly, so a model published this morning is runnable this morning. Search it here; pass what you find as model on an agent or a session, or as model to the model proxy.

The model object

string

Always model.

string

The model’s id. This is what model takes on an agent, a session and the proxy.

integer

Maximum context length in tokens, as the provider that will serve it publishes it.

integer

The longest reply this model may produce. It is also the output half of the pre-flight quote, so a model with a large allowance reserves more against your balance for the same prompt.

string[]

Which completion windows this model can run in. immediate is always present; priority and loose appear only for pool-hosted models.

string[]

Effort levels the model accepts, from what it publishes. Empty when it accepts none.

No price is published here, the same line GET /v1/media/models draws. What a call costs depends on the window it runs in and on which of the five token tiers its usage lands in; a single figure on this reply would be a guess. See the model router for how a call is metered, and Pricing.

List the catalogue

GET /v1/models — any valid key; no scope.

string

immediate, priority or loose. Narrows the list to models that window can actually serve — the same derivation the router refuses on, so a model listed for a window is never refused for it.

string

Free text, matched against a model’s id and name. Omit it to list them all.

number

Page size, 1–100. Defaults to 20.

string

The next_cursor of the previous page. Opaque — it is not a row id.

The catalogue runs to several hundred entries, so this reply is paged (Pagination). Nothing should assume one call returns the whole catalogue.

curl -fsSL "https://api.vetta.sh/v1/models?search=glm&limit=2" \
  -H "authorization: Bearer sk_live_..."

const page = await vetta.models.list({ search: "glm", limit: 2 });

vetta models list --search glm --limit 2

{
  "object": "list",
  "data": [
    {
      "object": "model",
      "id": "zai-org/GLM-5.2-FP8",
      "context_window": 1048576,
      "max_output_tokens": 32768,
      "supported_windows": ["immediate", "priority", "loose"],
      "efforts": ["high"]
    }
  ],
  "has_more": true,
  "next_cursor": "2"
}

Ordering is cheapest published input rate first, then by id, so a page boundary is stable within one read.

Retrieve one model

GET /v1/models/{id} — any valid key; no scope.

A model id contains a /, so it must be percent-encoded in the path: anthropic/claude-sonnet-5 becomes anthropic%2Fclaude-sonnet-5.

Use this when you already hold an id — the model an agent is set to, say — and want to know what it can do before you spend on it. It answers on the ids this route lists; a model the catalogue republishes under a different spelling is resolved for billing but is not itself an id you can retrieve.

curl -fsSL "https://api.vetta.sh/v1/models/anthropic%2Fclaude-sonnet-5" \
  -H "authorization: Bearer sk_live_..."

const model = await vetta.models.retrieve("anthropic/claude-sonnet-5");
console.log(model.supported_windows); // ["immediate"]

vetta models get anthropic/claude-sonnet-5

{
  "object": "model",
  "id": "anthropic/claude-sonnet-5",
  "context_window": 1000000,
  "max_output_tokens": 32768,
  "supported_windows": ["immediate"],
  "efforts": ["low", "medium", "high"]
}

Choose a model for a conversation

POST /v1/models/auto_select — scope proxy:write (or sessions:write). Idempotency-Key accepted. An optional add-on — the capability page is Model auto-selection. You name two to sixteen catalogue ids, each with one line on what it is for, and hand over the conversation so far; the reply is one of those ids, which you then pass unchanged as model to the model proxy, an agent or a session. It selects; it does not call the model it selected, and nothing about routing, the catalogue or vetta/auto changes whether or not you use it.

object

required

Catalogue id → description, 2 to 16 entries. Every key must be an id the catalogue lists, spelled exactly — an unknown id, an alias or vetta/auto is validation_failed with param: "options.<id>". A description is trimmed and must be 1 to 500 characters after trimming.

object[]

required

The conversation, 1 to 32 turns of { "role": "user" | "assistant", "content": string }, each content at least one character. The content lengths must sum to 32000 characters or fewer; over that the request is validation_failed with param: "messages". Nothing is trimmed, windowed or truncated for you — send less if you want less considered.

string

One of the options keys, else validation_failed with param: "default". Returned in place of the pick when min_confidence is set and not met.

number

A number above 0 and at most 1. Requires default — a threshold with nothing to fall back to is validation_failed with param: "min_confidence".

curl -fsSL "https://api.vetta.sh/v1/models/auto_select" \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{
    "options": {
      "anthropic/claude-sonnet-4.5": "Routine coding, edits and tool use",
      "openai/gpt-5.6-sol": "Hard multi-step reasoning or architecture",
      "google/gemini-3-flash": "Short factual answers where speed matters"
    },
    "messages": [{ "role": "user", "content": "What year did the Berlin Wall fall?" }],
    "default": "anthropic/claude-sonnet-4.5",
    "min_confidence": 0.5
  }'

const pick = await vetta.models.autoSelect({
  options: {
    "anthropic/claude-sonnet-4.5": "Routine coding, edits and tool use",
    "openai/gpt-5.6-sol": "Hard multi-step reasoning or architecture",
    "google/gemini-3-flash": "Short factual answers where speed matters",
  },
  messages,
  default: "anthropic/claude-sonnet-4.5",
  min_confidence: 0.5,
});
// pick.model is a catalogue id — pass it as `model` on the next call.

{
  "object": "model_selection",
  "model": "google/gemini-3-flash",
  "confidence": 0.81,
  "probabilities": {
    "anthropic/claude-sonnet-4.5": 0.12,
    "openai/gpt-5.6-sol": 0.07,
    "google/gemini-3-flash": 0.81
  },
  "defaulted": false,
  "spent_micro_usd": 11,
  "usage": { "input_tokens": 210 }
}

string

Always model_selection.

string

One of the options keys — the id to pass on.

number | null

The selector’s probability for its own choice; null when it reported no distribution.

object | null

The full distribution over the options keys, or null.

boolean

true only when default was returned in place of the selector’s pick.

integer

What this call debited, in micro-USD.

integer

The input tokens the selection consumed — the reported count, or the pre-flight estimate the debit was priced from when none was reported.

The selection rule. One choice is asked over options, about the conversation, with a fixed question: which option should answer the latest user message, given each option’s description.

Without min_confidence, model is the selector’s choice and defaulted is false.
With min_confidence, if confidence is null or below the threshold, model is default and defaulted is true; confidence and probabilities still report what the selector said. default does nothing without min_confidence.
An answer that is not one of the options keys is internal_error (500), never a silent default.

It fails closed. default is a confidence policy, not an outage policy. A deploy with no selector configured answers feature_not_configured (501); a selector that cannot be reached answers rate_limited (429) or internal_error (500), exactly as the model proxy does for an upstream failure. None of those costs anything. A caller who wants “use my default when selection is unavailable” catches the error and does so in their own code. What it costs. An organization-level call like the proxy: no reservation, no session hold, no session or agent id on the entry. The conversation is estimated before the call and the organization’s balance must cover the quote, else insufficient_credits (402) before any spend. Afterwards one debit, one input line item — the selector reads and emits nothing billable — booked under this request’s id and readable on GET /v1/credits/ledger. spent_micro_usd on the reply is what the ledger actually took. A refused or failed call is not debited.

Vetta Auto

vetta/auto is in the catalogue like any other id, and it picks the model per request. It serves immediate only. Because it publishes no rate card of its own, it is quoted against a price ceiling that is enforced upstream — a call that no model can serve within your budget is refused before it runs, never served at a higher price. See the model router.

Errors

Status	Code	When
400	`validation_failed`	`window` is not one of `immediate\|priority\|loose`. On `auto_select`: an unknown key (`param: "options.<id>"`), fewer than 2 or more than 16 options, more than 32 turns or more than 32000 characters of content (`param: "messages"`), a `default` that is not an option (`param: "default"`), a `min_confidence` with no `default` (`param: "min_confidence"`), or a body key the route does not take.
402	`insufficient_credits`	`auto_select`: the balance is below the pre-flight quote. Nothing was spent.
404	`not_found`	No model with that id — including an id this deploy cannot serve.
429	`rate_limited`	`auto_select`: the selector is busy. Retry shortly; nothing was spent.
500	`internal_error`	`auto_select`: the selector could not complete the request, or answered something that is not one of your options. Nothing was spent.
501	`feature_not_configured`	This deploy has no inference network configured — an empty list would say “the network publishes no models”, which is a different fact. On `auto_select`: this deploy has no selector configured.

A transient failure to reach the network answers 500 rather than a stale or empty catalogue. The failed read is not cached, so an immediate retry is the right response to one.

Next: the model router

How a call is routed, what the completion window changes, and how tokens are metered.

Introduction

Core resources

Platform

Identity

The model object

List the catalogue

Retrieve one model

Choose a model for a conversation

Vetta Auto

Errors

Next: the model router

​The model object

​List the catalogue

​Retrieve one model

​Choose a model for a conversation

​Vetta Auto

​Errors

Next: the model router

The model object

List the catalogue

Retrieve one model

Choose a model for a conversation

Vetta Auto

Errors