> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# models

> The model catalogue a caller picks from — client.models.

Three methods: two read the catalogue, one picks from it. The catalogue is read live from the network, so it is cursor-paged like every other listing — and a model published this morning is listed this morning.

## list

```ts theme={"system"}
client.models.list(query?: {
  window?: string;
  search?: string;
  limit?: number;
  after?: string;
}): Promise<Page<Model>>
```

`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:

<ResponseField name="id" type="string">The model id you pass as `model` on [`agents.create`](/docs/sdk/agents#create).</ResponseField>
<ResponseField name="context_window" type="integer">Native context size in tokens.</ResponseField>
<ResponseField name="max_output_tokens" type="integer">The longest reply this model may produce, and what the pre-flight quote is bounded by.</ResponseField>
<ResponseField name="supported_windows" type="Window[]">The window configurations this model can serve.</ResponseField>
<ResponseField name="efforts" type="(&#x22;low&#x22; | &#x22;medium&#x22; | &#x22;high&#x22;)[]">The effort levels this model accepts.</ResponseField>

```ts theme={"system"}
const models = await client.models.list({ search: "glm", limit: 5 });
```

## retrieve

```ts theme={"system"}
client.models.retrieve(id: string): Promise<Model>
```

`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.

```ts theme={"system"}
const model = await client.models.retrieve("zai-org/GLM-5.2-FP8");
```

## autoSelect

```ts theme={"system"}
client.models.autoSelect(body: {
  options: Record<string, string>;                       // catalogue id → what it is for, 2–16 entries
  messages: { role: "user" | "assistant"; content: string }[]; // 1–32 turns, ≤ 32000 characters in all
  default?: string;                                      // one of the options keys
  min_confidence?: number;                               // > 0 and ≤ 1; requires `default`
}): Promise<ModelSelection>
```

`POST /v1/models/auto_select`. An **optional add-on** — a choice over ids you name, given the conversation so far ([Model auto-selection](/docs/concepts/model-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`](/docs/sdk/proxy), 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`.

```ts theme={"system"}
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 concrete catalogue id the caller then passes to proxy.messages / an agent's `model`.
```

The same `{ options, min_confidence }` policy can also ride on the call itself as `model_selection` — on [`proxy.messages` / `proxy.completions`](/docs/sdk/proxy) per call, or on an [agent](/docs/sdk/agents) 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](/docs/concepts/model-selection#select-during-a-call).

<ResponseField name="model" type="string">One of the `options` keys.</ResponseField>
<ResponseField name="confidence" type="number | null">The selector's probability for its own choice; `null` when it reported no distribution.</ResponseField>
<ResponseField name="probabilities" type="Record<string, number> | null">The full distribution over the `options` keys, or `null`.</ResponseField>
<ResponseField name="defaulted" type="boolean">`true` only when `default` was returned in place of the selector's pick.</ResponseField>
<ResponseField name="spent_micro_usd" type="number">What this call debited, in integer micro-USD — what the ledger actually took.</ResponseField>
<ResponseField name="usage" type="{ input_tokens: number }">The input tokens the selection consumed, or the pre-flight estimate when none were reported.</ResponseField>

`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`](/docs/sdk/credits). `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](/docs/api/models#choose-a-model-for-a-conversation).

<Note>
  `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](/docs/concepts/model-router#vetta-auto).
</Note>