# Auto Model

Auto picks a model for every message. Send `model: "auto"` and Auto chooses the model, the reasoning effort and the speed tier for that one message, inside the rules your organisation set, and tells you which one it picked. This page explains what Auto does, how admins steer it, and which endpoints read and change it.

The audience is two people: the **organisation admin** who decides what Auto may use, and the **developer** who sends `model: "auto"` and shows people what happened.

## What Auto is

`auto` is an entry in the [model list](/api-reference/models/list) like any other model, named **Auto**. It never answers itself. For each user message it:

1. reads the message,
2. looks at every model, effort and speed tier your rules allow,
3. picks the one that best balances quality, speed and cost for that message,
4. runs the turn on the picked model.


The turn is billed as a turn of the model Auto picked, exactly as if you had sent that model yourself. The pick is announced during the turn as one [`response.model_selected`](/api-reference/objects/streaming-event-object) stream event, before the first content, and can be read again later from [Get why Auto picked a reply's model](/api-reference/threads/get-message-route).

Auto picks once per user message and keeps that model for every tool round of the turn, so the turn's prompt cache is not thrown away halfway through.


```bash
curl https://api.aitronos.com/v1/model/response \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_7d2c9e41a5b84f0e9c3a1b2d4e6f8a0c",
    "model": "auto",
    "inputs": [{"role": "user", "content": "Find the race condition in this worker"}],
    "stream": true
  }'
```

## What matters most

Every pick weighs three things: **quality**, **speed** and **low cost**. The weights always add up to 1. People and admins choose them through four presets; admins can also set the three weights directly (**Custom**).

| Preset | Key | Quality | Speed | Cost | When to use it |
|  --- | --- | --- | --- | --- | --- |
| Balanced | `balanced` | 0.60 | 0.20 | 0.20 | The default. Good answers without waiting or spending more than needed. |
| Best quality | `best_quality` | 0.85 | 0.075 | 0.075 | Stronger models and more thinking, even when slower. |
| Faster | `faster` | 0.25 | 0.65 | 0.10 | Shorter waits. Good for quick questions. |
| Lower cost | `lower_cost` | 0.25 | 0.10 | 0.65 | Lighter models where they are good enough. |


Do not copy this table into a client: [Get the Auto model option catalogue](/api-reference/auto-model/get-catalog) returns the presets, their labels and descriptions in the reader's language, their weights, the five effort levels and the default preset, in display order.

## Rules and who sets them

Auto's behaviour is decided by layers of rules. From the broadest to the most specific:

1. **Platform default** — Balanced, every allowed model, any effort, no cost limit, people can choose.
2. **Organisation** — the organisation's own rule.
3. **Departments** — the rule of every department from the top of the tree down to the person's **primary department**. A person in several departments has one primary department; an admin picks it with [Set a member's primary department](/api-reference/organizations/members/set-primary-department).
4. **Assistant** — the rule of the assistant the chat runs with.
5. **The person's own choice** — one of the four presets ([Set my Auto priority](/api-reference/auto-model/set-my-choice)).
6. **The chat's choice** — a preset for one chat (`auto_choice` on [Update per-thread user state](/api-reference/threads/update-per-thread-user-state), or on the first message of a new chat in [Create a response](/api-reference/responses/create)).


**What matters most** is decided by the most specific layer that sets it, so an assistant built for legal work can ask for quality even in a department that prefers speed. Two switches change that:

- **Enforced.** A rule with `enforced: true` locks its preset: nothing below it can change it. When two enforced rules disagree, the broader one wins (organisation over department over assistant), and both rules report the clash.
- **People can choose.** A rule with `people_can_choose: false` stops people and chats below it from choosing their own preset. `null` means the rule inherits the value above it.


**Limits are always the strictest of every layer** and are never overridden:

- **Allowed models** (`pool`) — `all_allowed` (every model the scope allows, including models added later) or `pick` (only the listed models). Several pick lists intersect.
- **Effort range** (`effort.min` .. `effort.max`) — from `off`, `low`, `medium`, `high`, `max`. Ranges intersect; a rule whose range does not overlap the range above it is refused (`AUTO_MODEL_EFFORT_RANGE_EMPTY`).
- **Cost limit per message** (`max_chf_per_message`) — in CHF; the lowest set limit applies, and a rule cannot raise an inherited one.
- **Priority serving** (`allow_priority_tier`) — Auto may use a faster, dearer speed tier only if every layer allows it.
- **Switched off** (`enabled: false`) at any layer means off for everyone below it.


Admins edit organisation and department rules (capability `manage_users`). An assistant's editors edit that assistant's rule, but cannot loosen anything enforced above it (`AUTO_MODEL_LOOSENS_ENFORCED`). [Check who gets what](/api-reference/auto-model/get-effective-settings) shows, for one person and optionally one assistant, which value each layer set and which one won.

### When no model fits

If the rules leave no model that can answer a message — for example a pick list whose only model was switched off, or a cost limit below every model's estimate — the turn fails with `422 AUTO_MODEL_POOL_EMPTY` (or the same code in the stream's error event). Auto never silently falls back to a model outside the rules. `error.details` names the rule to change (`rule`: its layer, id and name) and why nothing was left (`why`: `pool`, `capabilities`, `effort` or `cost_limit`).

## How a pick is made

For each message Auto works out:

- **the task** — chat, writing, translation, coding, analysis, research, tool work or extraction;
- **how hard it is** — from very easy (0) to very hard (4);
- **the stakes** — low (0) to high (2);
- whether it needs **careful reasoning**, and whether a **short answer** is enough.


It then estimates, for every model and effort your rules allow, how well it fits the message, how long until its first word and what it will cost, and picks the best balance for the weights in force. The pick never leaves the allowed models and never exceeds the effort range or the cost limit.

- A **short message** (a few words, no attachment, no code, nothing that needs a tool) is read quickly without the full analysis; the event then says `basis: "heuristic"` and the summary reads "Quick read". The same quick read is used if the full analysis does not answer in time.
- A **follow-up in the same task** keeps the model it already used when switching to a cheaper one would not pay for losing the conversation's cache (`basis: "sticky"`). Moving to a stronger model happens at once.
- With `model: "auto"`, any `reasoning.effort` or `speed_tier` in the request is replaced by Auto's pick. Admin limits bound effort, and a request field cannot bypass them.


The `summary` of the event and of the route read describes what Auto read, in the person's language, for example "Coding, hard, needs careful reasoning".

## Retry smarter, retry faster

Regenerating an Auto reply can ask for a different direction with `auto_retry` on [Create a response](/api-reference/responses/create):

- `"smarter"` picks a model or effort that fits the message better;
- `"faster"` picks one that answers sooner;
- `null` regenerates it as a new Auto turn.


The route read's `retry.smarter` and `retry.faster` say whether each direction is still worth offering. When the rules allow nothing stronger or faster, the reply is regenerated on the same model and effort and the event carries `retry_exhausted: true` — the retry runs, it is never refused. A reply whose choice is no longer kept (after 90 days) returns `AUTO_MODEL_ROUTE_NOT_FOUND`.

## Learning from your organisation

Auto watches what people do after an answer: asking for a smarter answer, asking for a faster one, regenerating, or switching away from Auto. Over time, these signals shift how much quality Auto asks for in your organisation — slowly, and only within fixed bounds. Nothing is learned across organisations: one organisation's habits never change another's picks.

## Analytics

[Get Auto model analytics](/api-reference/auto-model/analytics) (capability `view_billing`) reports for a period, for the organisation and per rule:

- **what Auto spent**, including the small cost of choosing models;
- **what the same replies would have cost on FTG 4** (the same tokens priced on FTG 4), and the saving — negative when Auto cost more;
- **the models Auto picked**, as shares;
- **the average time to the first word**;
- **how often people asked for a smarter answer**.


Figures need enough data: money figures appear once at least 20 replies of the rule (or the organisation) could be measured; speed figures once at least 20 replies have a measured first word. Below that, the values are `null` with `enough_data: false` — never `0`. Auto keeps 90 days of detail, so `data_from` says the first day the figures can cover.

## Default for new chats

Once Auto is generally available it becomes the default model for new chats where nobody chose a model: the organisation has no default model and the assistant still uses the platform's default. A model somebody chose — an organisation default, an assistant's own model, or a model picked in the chat — always wins. Until then, Auto is an opt-in entry in the model picker.

## Turning it on

Auto sits behind the `auto_model` feature switch. While it is off for your organisation, every Auto model endpoint answers `404` with code `AUTO_MODEL_NOT_ENABLED`, and `model: "auto"` is refused with the same code, so a client can tell "not switched on" from a wrong address and hide the feature. Key on the code; the message reads "Auto isn't available for this organisation." in the reader's language.

## Endpoints

| Endpoint | What it is for | Who |
|  --- | --- | --- |
| [`GET /v1/auto-model/catalog`](/api-reference/auto-model/get-catalog) | Presets, effort levels, default preset | any member |
| [`GET /v1/organizations/{organization_id}/auto-model/rules`](/api-reference/auto-model/list-rules) | Every rule, with clashes | `manage_users` |
| [`GET …/auto-model/rules/{scope_type}/{scope_id}`](/api-reference/auto-model/get-rule) | One rule, what it inherits, its bounds | `manage_users`, or the assistant's editors |
| [`PUT …/auto-model/rules/{scope_type}/{scope_id}`](/api-reference/auto-model/update-rule) | Save a rule | `manage_users`, or the assistant's editors |
| [`DELETE …/auto-model/rules/{scope_type}/{scope_id}`](/api-reference/auto-model/reset-rule) | Remove or reset a rule | `manage_users`, or the assistant's editors |
| [`GET /v1/organizations/{organization_id}/auto-model/effective`](/api-reference/auto-model/get-effective-settings) | Check who gets what | yourself, or `manage_users` |
| [`POST /v1/organizations/{organization_id}/auto-model/simulate`](/api-reference/auto-model/simulate) | Preview a rule on sample messages | `manage_users`, or the assistant's editors |
| [`GET /v1/users/me/auto-model`](/api-reference/auto-model/get-my-choice) | Your own priority | yourself |
| [`PUT /v1/users/me/auto-model`](/api-reference/auto-model/set-my-choice) | Set or clear your own priority | yourself |
| [`PUT /v1/organizations/{organization_id}/members/{user_id}/primary-department`](/api-reference/organizations/members/set-primary-department) | A member's primary department | `manage_users` |
| [`GET /v1/threads/{thread_id}/messages/{message_id}/route`](/api-reference/threads/get-message-route) | Why Auto picked a reply's model | anyone who may read the thread |
| [`GET /v1/analytics/auto-model/{org_id}`](/api-reference/auto-model/analytics) | Spend, saving, picks, speed | `view_billing` |


Related pages:

- [Auto model API introduction](/api-reference/auto-model/introduction)
- [Auto model rule object](/api-reference/objects/auto-model-rule-object)
- [Auto model route object](/api-reference/objects/auto-model-route-object)
- [Create a response](/api-reference/responses/create) — `model: "auto"`, `auto_choice`, `auto_retry`
- [Streaming events](/api-reference/objects/streaming-event-object) — `response.model_selected`
- [Get per-thread user state](/api-reference/threads/get-per-thread-user-state) and [Update per-thread user state](/api-reference/threads/update-per-thread-user-state) — `auto_choice`
- [List models](/api-reference/models/list) and [Model object](/api-reference/objects/model-object) — the `auto` entry