Skip to main content
Most callers do not know the right budget for a given request. A retrieval that usually needs 2,000 tokens occasionally needs 8,000, and picking one number means either overspending on the common case or under-serving the hard one. Adaptive mode solves that from the other direction: you define a ladder, and the engine climbs it only as far as it has to.
Selection is attempted at 2,000 tokens. If that selection is judged insufficient, it escalates to 4,000, then 8,000, and — if allow_full_context_fallback is on — finally to passing your context through intact. The response tells you exactly how far it went:
This is per-request, and it is decided by the engine on the evidence in the request. It is not a per-tenant setting, and there is nothing to configure ahead of time.

​
When to use it

Use adaptive

Heterogeneous requests where difficulty varies — a support queue, a document Q&A surface, an agent loop whose turns differ wildly in how much state they need. The common case gets the small budget; the hard case gets what it needs.

Use fixed

A hard downstream constraint you must not exceed, or a uniform workload where you already know the right number. Fixed does one selection pass, so it is the cheaper and more predictable of the two.

​
The fields

max_context_tokens still applies as the outer bound. Set your top rung at or below it — a rung above it buys nothing.
mode: "adaptive" with a null or missing adaptive object silently runs as a fixed-budget request. It is not an error. If adaptive behaviour matters to you, assert on attempted_budget_tokens in your integration tests: a fixed-path response leaves it empty.

​
allow_full_context_fallback

Leave it true unless you have a hard downstream cap that full context would blow — a model window you cannot exceed, or a contractual token limit. With it false, a request that cannot be satisfied within the ladder returns the best selection found rather than everything. That is the right behaviour for a hard cap and the wrong behaviour for an ordinary quality-sensitive path, where “send everything” is a better answer than “send an under-budget subset”.

​
What it costs

Each rung attempted is a full selection pass. A workload that always escalates to the top rung does several times the work of one that succeeds on the first. That will not cost you more: the meter counts the input you submitted, once, regardless of how many rungs were climbed (metering is not live yet, and this is how it is defined). What it does cost you is latency, which is the reason to watch it. Watch attempted_budget_tokens in production:
  • Mostly [2000] — your first rung is well chosen.
  • Mostly [2000, 4000, 8000] — your first rung is too small. Raise it. You are paying three passes of latency to arrive somewhere you could have started.
  • Ladder is never climbed at all — you may not need adaptive mode.
A reasonable starting shape is a first rung near the median of what your workload actually needs, one or two escalations, and a top rung at your real downstream limit. Three rungs is usually enough; ten is a latency budget spent on ceremony.
Raising a rung is a latency and fit decision, not a quality one. Selections at different rungs are different computations, and a higher rung is not guaranteed to produce a superset — or a better set — than a lower one. Size the ladder from what your downstream call can accept and from how often you are escalating. Do not sweep the rungs looking for a quality optimum, and do not expose them to an end user as a quality control.

​
Reading the result

​
Coverage checking

Adaptive mode pairs naturally with budget.require_evidence_coverage. With it set, the engine runs its coverage check and prefers standing down to full context over returning a selection that does not cover the task’s evidence. The verdict is summarised in safety.
Use it where a missing piece of evidence produces a confidently wrong answer rather than an obviously incomplete one — regulated answers, citations, anything a human will act on without re-checking.