
Use a preflight estimate to decide whether a specific request has enough room for its intended response. After execution, compare the estimate with reported input usage and inspect the stop reason. Keep this admission decision separate from your cost ledger.
Count the Request You Will Actually Send
Your latest prompt might be a short question while the assembled request contains a long debugging session. Build one request snapshot after retrieval, history selection and tool selection. Count that snapshot; send the same content. If a middleware layer adds instructions afterward, invalidate the estimate and count again.
Inventory the system prompt, messages, previous assistant responses, tool results, tool definitions and attachments. Anthropic documents that these components, plus generated output, occupy context. See its context-window guide. Keep a request digest and configuration version beside your estimate so you can investigate differences without storing raw private prompts.
Do not treat tool schemas as incidental metadata. A request with one short question and many detailed tool definitions deserves its own preflight check. The same applies when you replace a paragraph with an image or PDF: do not substitute a character count for the supported attachment representation. For deciding which material belongs in the request, read The True Cost of Context.
Use the Provider Endpoint within Its Supported Scope
For Claude, send the chosen model and supported structured inputs to POST /v1/messages/count_tokens; read input_tokens from the result. The API reference defines the request fields. Share a request builder between counting and generation, with an explicit projection for the count endpoint rather than blindly forwarding every generation parameter.
The token-counting guide describes this as an estimate and says it does not run caching logic. It currently rejects server tools except advisor, the MCP connector, and image or document blocks using URL or file sources. Supported images and PDFs must use base64 for counting. Do not delete unsupported components merely to obtain a reassuring number and then label it the whole request.
For an unsupported request, mark preflight coverage incomplete and choose a separate, tested handling path. For example, route it to an adapter with explicit limits and observed usage, or require a smaller supported input. A partial count can be useful diagnostically, but keep that status visible to the admission policy. Count again when you switch models; the endpoint uses the selected model's tokenizer.
Reserve Space for the Response You Need
Define your own admission rule: estimated input plus intended output allowance plus an application margin must fit the configured context window. Fetch the window and output ceiling from current model documentation. Do not hard-code one capacity across model families. Keep any separate request-size or attachment limits in the adapter as additional checks.
For a synthetic 10,000-token window, suppose input is estimated at 7,000 tokens, output allowance is 2,000, and your experimental margin is 1,000. The policy admits equality at 10,000. One additional estimated input token causes rejection. These are deliberately small fixture values, not a Claude model specification or a recommended universal margin.
Choose the output allowance from the task: a short classification and a multi-file patch need different experiments. Measure whether successful outputs finish inside the allowance. If your application margin causes too many rejections, revise it from representative observations rather than quietly removing it. A larger margin spends available context on uncertainty; a smaller one accepts more risk of a boundary stop.
Thinking shares Claude's output budget. Previous thinking-block retention depends on the model: Opus 4.5 and later preserve it by default, while earlier Opus models strip it. The context guide also distinguishes overflow: oversized input returns a 400 error; on Claude 4.5 and newer, input plus requested output can exceed the window, with generation stopping at model_context_window_exceeded. Older-model behavior differs. API acceptance therefore does not prove that your desired response fits.
Compare Estimates with Reported Usage
After generation, record the request digest, model, estimate, configured output allowance, reported input categories, output usage and stop reason. For a comparable supported request, compute reported input minus estimated input. Keep the signed difference so you can distinguish underestimation from overestimation. Investigate changes by request shape rather than blending plain text, tool-heavy requests and PDFs into one average.
Under Claude caching, input_tokens alone is not total input. Add it to cache_read_input_tokens and cache_creation_input_tokens, as documented in prompt-caching usage tracking. In a synthetic response with 200 uncached tokens, 6,000 cache-read tokens and 800 cache-creation tokens, total input is 7,000. Comparing only 200 against a 7,000-token estimate would manufacture a large discrepancy.
Do not add that total to nested cache-duration subtotals again. Keep cost reconciliation in the AI cost guide, where measured categories and applicable rates belong. Here the question is narrower: did the estimate describe this input well enough for admission, and did the response complete within its space?
Exercise the Boundary before Connecting an API
The following complete Node.js fixture tests the application arithmetic and cache-category normalization. Save it as token-policy-test.cjs and run it with Node.js. It does not tokenize text, construct a provider request, validate SDK compatibility or predict actual model output.
const assert = require('node:assert/strict');
function admit(estimate, output, margin, window) {
for (const n of [estimate, output, margin, window]) {
if (!Number.isSafeInteger(n) || n < 0)
throw new TypeError('nonnegative safe integers required');
}
if (output === 0 || window === 0)
throw new RangeError('output and window must be positive');
// Subtraction avoids unsafe addition near MAX_SAFE_INTEGER.
const available = window - output - margin;
return available >= 0 && estimate <= available;
}
function inputTotal(usage) {
return ['input_tokens', 'cache_read_input_tokens',
'cache_creation_input_tokens'].reduce((sum, key) => {
const n = usage[key] ?? 0;
if (!Number.isSafeInteger(n) || n < 0 ||
!Number.isSafeInteger(sum + n))
throw new TypeError('invalid input usage');
return sum + n;
}, 0);
}
const cases = [
[7000, 2000, 1000, 10000, true],
[7001, 2000, 1000, 10000, false],
[0, 2000, 1000, 10000, true],
[0, 9000, 2000, 10000, false],
[8000, 2000, 0, 10000, true]
];
for (const [i, o, m, w, expected] of cases)
assert.equal(admit(i, o, m, w), expected);
for (const bad of [-1, NaN, Infinity, 0.5, Number.MAX_SAFE_INTEGER + 1])
assert.throws(() => admit(bad, 2000, 1000, 10000));
assert.throws(() => admit(1, 0, 0, 10000));
assert.throws(() => admit(1, 1, 0, 0));
assert.equal(inputTotal({input_tokens: 200,
cache_read_input_tokens: 6000, cache_creation_input_tokens: 800}), 7000);
assert.equal(inputTotal({input_tokens: 7000}), 7000);
assert.throws(() => inputTotal({input_tokens: -1}));
assert.throws(() => inputTotal({input_tokens: Number.MAX_SAFE_INTEGER,
cache_read_input_tokens: 1}));
console.log('PASS: 16 synthetic checks; no API calls');
The 16 synthetic checks passed locally on November 17, 2026. They cover equality, one-token overflow, empty estimated input, oversized reservations, a zero margin, invalid numeric inputs, zero capacity, missing cache categories and usage overflow. No live API call was performed. The output is evidence about these functions and fixtures only.
Next, run integration cases in your own environment: the identical payload counted and generated; a payload mutated after counting; a full tool-result continuation; a base64 attachment; an unsupported server-tool request; a model switch; and a response that ends at a context or output boundary. Assert both admission status and completion status. Keep an error distinct from a valid count of zero, and avoid retrying an oversized request unchanged.
FAQ
Can I count just the latest user prompt?
Count the assembled request, including system instructions, history, tools and supported attachments. The latest user prompt is only one part of the input.
Does prompt caching create more context space?
No. Cached tokens still occupy context space. Add uncached input, cache reads and cache creation when comparing reported input with a preflight estimate.
Does max_tokens reserve that many answer tokens?
It sets an output ceiling, not a promise of a complete answer. Thinking shares that output budget, and context limits can stop generation.
Is a token estimate a billing total?
No. Use the estimate for request admission, then record reported usage. Cost reconciliation also needs the applicable token categories and pricing rules.
Sources and Review Trigger
- Claude token counting: supported inputs, limitations and estimate semantics.
- Count tokens API reference: endpoint and structured request contract.
- Claude context windows: capacity, thinking and overflow behavior.
- Claude prompt caching: usage categories and total-input calculation.
Sources checked November 17, 2026. Review by December 17, 2026, or sooner if model capacity, supported counting inputs, thinking retention or usage fields change. This article gives no prices or live accuracy measurement.