Auto mode
Send model: auto and ACOG grades each request and routes it to the cheapest model strong enough to answer it, across every provider you have connected.
Most requests do not need your most capable model. Auto mode grades how hard each request is and sends it to the cheapest model that can handle it. It applies only to requests that ask for it with "model": "auto"; a request that names a model is answered by that model, except in two documented cases you can switch off: the semantic cache can reuse an equally or more capable model’s stored answer, and the policy-block fallback retries a refused request once on another model (switched off per request).
curl -s https://gateway.acog.tessarac.com/v1/chat/completions \
-H "Authorization: Bearer $ACOG_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "auto", "messages": [{"role": "user", "content": "What is the capital of France?"}]}'The response header x-acog-resolved-model names the model that answered.
With auto mode off
auto always works. With auto mode off, it resolves to your default connection’s default model. That is a convenient way to change the model all your auto callers use from one place, under Admin → Providers.
Turning auto mode on
Open Admin → Cost policies → Auto mode (requires the Connect and disconnect AI provider accounts permission) and switch it on. Changes apply from the next request.
Tiers
Every model in your pool is placed on one of four tiers by what it can do, never by its price:
| Tier | Name | For |
|---|---|---|
| 1 | Lightweight | Simple requests: greetings, lookups, short answers |
| 2 | Balanced | Everyday work with a clear, bounded scope |
| 3 | Advanced | Multi-step reasoning and hard problems |
| 4 | Frontier | Open-ended design and the hardest problems |
Each auto request is graded and sent to the cheapest model on the lightest tier that can handle it, or on a higher tier if that is cheaper.
ACOG places known models on its reference ladder. You can move any model to a different tier; your choice sticks, even after a re-evaluation. Re-evaluate re-grades models ACOG has no reference placement for; you are notified when it starts and finishes.
The pool
The pool is built from the models declared on your connections. You can narrow it to some platforms or model families, and add specific models. You never enter prices: ACOG knows each provider’s list prices.
Your default model as a ceiling
| Choice | Effect |
|---|---|
| Use my default model as the ceiling | Auto mode never routes to a model priced above your default model |
| My default is where most traffic should go | Auto mode may route above your default for hard requests. Those requests save nothing: you pay the stronger model’s price, and no saving is counted or billed. |
How a request is graded
- A free structural check settles requests whose difficulty is clear from their shape alone.
- Otherwise a small, cheap judge model reads the request and grades it. The judge is the cheapest model in your own pool that answers, on your own connection, so it is billed by your provider and appears in reports as
acog-internal-judge. - On any doubt or error, the request goes to the strongest tier. A wrongly cheap answer is worse than a missed saving.
Requests that need images or tools are sent only to models that support them.
Checking the answer
After a model chosen by auto mode answers, ACOG checks the answer before returning it, including an answer replayed from cache. The check runs inside the gateway and makes no model call. An answer fails it when it is empty, when its opening reads as a refusal, or when the request asked for structured output (a JSON response format, tools or functions) and the answer is not JSON. A failed answer is sent again to the next model in auto mode’s ranked list for that request, within the same limit of five attempts as below; if no candidate is left, the last answer is returned. Streamed responses are not checked, because a stream has already reached you as it is produced.
Conversations stay on one model
Auto mode keeps a conversation on a stable choice so it does not switch models mid-task. It recognizes a conversation by these request headers, if your client sends one: x-acog-session-id, x-session-id, x-claude-code-session-id. Agent and sub-agent identity is read from x-acog-agent-id, x-agent-id or x-claude-code-agent-id.
When a model is not available
If the chosen model is refused because your provider account cannot use it (422 model_access_required), auto mode tries the next suitable model, up to five attempts.
How auto mode savings are measured
A request auto mode sends to a cheaper model saves the difference between the price of your default model and the price of the model that answered. The saving is never more than what the default model would have cost. See How savings are measured.
Data residency
The judge reads the request’s text on the connection its model is configured on. If you keep traffic inside a region, make sure the judge’s connection is pinned there too. See Google Vertex AI.