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

# Models

> Catalog fields, selector grammar, and what a turn pins.

`GET /v1/models` lists every model the workspace can use.
`GET /v1/agents/{agentId}/models` narrows that to one agent and names its
current default. Both are cursor-paginated with `limit` up to 200.

## Catalog fields

| Field | What it tells you |
| - | - |
| `id` | The value you put in a profile, such as `anthropic/claude-sonnet-5`. |
| `provider` | `anthropic`, `openai`, `google`, `xai`, `fireworks`, `bedrock`. |
| `apiFamily` | The wire adapter, such as `anthropic_messages` or `openai_responses`. |
| `providerModel` | The upstream model identifier Matrices routes to. |
| `contextWindowTokens`, `maxOutputTokens` | Size limits. |
| `inputModalities`, `outputModalities` | `text`, `image_input`. |
| `supportsTools`, `supportsThinking` | Whether tool use and hidden reasoning are available. |
| `reasoningEffort`, `thinkingBudgetTokens` | Reasoning defaults, when the model has them. |
| `cacheRetention` | `none`, `short`, or `long`. |
| `cost` | Rates in USD per million tokens. |

`cost` carries `input` and `output`, optional `cacheRead`, `cacheWrite`, and
`reasoning`, plus `tiers`. Each tier restates those rates above a
`contextOverTokens` prompt-size threshold.

## Selector grammar

A profile's `models` is an ordered list of up to eight selectors, at most 512
characters each:

| Form | Example | Authorizes |
| - | - | - |
| Exact | `anthropic/claude-sonnet-5` | That one catalog entry. |
| Prefix wildcard | `anthropic/*` | Every current match, plus future ones. |
| Everything | `*` | The whole catalog. |

Each selector authorizes all of its current matches and contributes one
preferred concrete target, chosen by catalog precedence. Selector order then
picks the profile's default. Wildcards are dynamic: a new matching model becomes
usable without a profile edit.

A turn's optional `model` field must be a concrete catalog ID that the
profile's selectors authorize. Wildcards are rejected there, and `model` is not
accepted alongside `mode: "steer"`.

## What a turn pins

The turn snapshot's `resolvedConfig.model` is the concrete target the turn will
use: `id`, `provider`, `apiFamily`, `providerModel`, the token limits, the
modality and capability flags, `imageInputFormats`, and the reasoning and cache
settings. Changing a profile's `models` moves the next admitted turn, never one
in flight.

## Usage accounting

Events and turn results carry `usage`: `inputTokens`, `outputTokens`,
`totalTokens`, and, where they apply, `cacheReadTokens`, `cacheWriteTokens`,
`reasoningTokens`, and `estimatedCost` in USD. That estimate is what an agent
`budget` and a thread `maxCost` are measured against.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.