Your Claude integration works with a short question. Then someone uploads a long report, adds several previous conversations, and asks for a detailed answer. The request becomes much larger than the one your team tested during development.
At that point, a character limit is not enough. A document’s page count does not tell you how much space its extracted text, instructions, conversation history, and tool definitions will occupy together. Nor does a successful small request prove that your gateway exposes the controls needed to manage a larger one.
Claude API token counting gives you a way to inspect input size before generation. The useful business outcome is a predictable admission decision: send this request, reduce it, move it into a different workflow, or explain to the user why it cannot proceed unchanged.
This guide builds that decision around a Claude API gateway. It focuses on preparing requests, reserving capacity, handling unavailable counting endpoints, and checking whether a gateway integration gives you enough information to operate responsibly.
Start with the request your application actually sends
A common budgeting mistake begins before the first API call. The team counts the user’s latest message, while the application sends considerably more material.
A document assistant might include a system instruction, a response format description, retrieved passages, several previous messages, a glossary, and definitions for tools the model may use. Each component exists for a reason, but they all contribute to the request your application must accommodate.
Create one request-building function and use its result for both counting and generation. Do not maintain a separate “estimated prompt” that gradually diverges from the production request.
For example, if the retrieval layer adds ten passages after your counting step, the earlier measurement no longer represents the request. Move counting after retrieval and after any template expansion. If the user changes the document or adds a message, invalidate the previous measurement.
This is especially important in applications where several teams own different parts of the prompt. A small addition by each team can create a large combined increase.
Understand what the counting endpoint tells you
Claude documents a dedicated POST /v1/messages/count_tokens endpoint. It accepts supported structured inputs and returns an input_tokens value. The result concerns input size; it is not a prediction of the final answer length or a complete invoice. Some input types accepted by generation have separate counting limitations, so check the current documentation for your request shape.Claude Platform Docs
Use the official Claude token-counting guide to confirm the current endpoint contract.
When accessing Claude through an intermediary, verify that endpoint separately. A gateway may support message generation while not exposing token counting on the same route.
Before spending time debugging a count request, confirm the complete URL, authentication header, supported model identifier, and account permissions. Treerouter’s Claude gateway verification guide provides a useful starting point for that conversation.
Build an input admission policy
Your application needs a policy rather than a single magic number.
Define an input ceiling for the workflow. Reserve room for the answer and any additional material that your chosen execution pattern may require. Consult the model’s current context rules instead of assuming every Claude model handles the same request identically.
For an ordinary text-only workflow, an application might use this simplified planning relationship:
planned input allowance
= verified context allowance
- reserved output allowance
- application safety marginThis is an application budgeting rule, not a universal formula for every thinking mode, server tool, or conversation-management feature. Use the relevant Claude context-window documentation when those features are involved.
Keep the policy configurable. A short classification endpoint and a detailed document-analysis endpoint should not inherit identical limits merely because they share a model provider.
Also distinguish the application ceiling from the provider maximum. You may intentionally accept smaller requests to keep response times, operating costs, and user expectations manageable.
Prepare a minimal counting request
The following Python example makes one counting request and checks an application-defined input ceiling. It deliberately does not generate an answer.
It uses only the Python standard library. CLAUDE_COUNT_URL must contain the complete counting endpoint confirmed for your route. The authentication header and value are also configurable because an official API credential and a gateway credential are not interchangeable.
import json
import os
import urllib.error
import urllib.request
count_url = os.environ["CLAUDE_COUNT_URL"]
auth_header = os.environ["CLAUDE_AUTH_HEADER"]
auth_value = os.environ["CLAUDE_AUTH_VALUE"]
model = os.environ["CLAUDE_MODEL"]
input_ceiling = int(os.environ.get("APP_INPUT_CEILING", "20000"))
payload = {
"model": model,
"system": "Summarize the supplied material accurately.",
"messages": [
{
"role": "user",
"content": "Summarize this short demonstration document."
}
]
}
request = urllib.request.Request(
count_url,
data=json.dumps(payload).encode("utf-8"),
headers={
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
auth_header: auth_value
},
method="POST"
)
try:
with urllib.request.urlopen(request, timeout=30) as response:
result = json.load(response)
except urllib.error.HTTPError as exc:
raise RuntimeError(
f"Counting failed with HTTP {exc.code}; "
"inspect the redacted response securely."
) from None
input_tokens = result.get("input_tokens")
if type(input_tokens) is not int or input_tokens < 0:
raise RuntimeError("No valid input_tokens value was returned.")
decision = "allow" if input_tokens <= input_ceiling else "reduce_input"
print({
"model": model,
"input_tokens": input_tokens,
"input_ceiling": input_ceiling,
"decision": decision
})The value 20000 is an illustrative application limit. It does not describe a Claude model limit or a Treerouter quota. Replace it with a ceiling justified by your workload and verified model configuration.
This sample has not been executed against a live Treerouter account. Confirm counting support before treating it as an integration recipe.
Make counting and generation refer to the same input
Once counting succeeds, your next problem is consistency.
Suppose a user submits a report, your system counts it, and then a background process updates the conversation before generation begins. The count may be valid for the earlier request but wrong for the later one.
A practical implementation should associate the measurement with a request snapshot. Record a hash or internal version of the serialized input, the model identifier, and the counting result. Before generation, confirm that the request still matches the snapshot.
Avoid recording the complete prompt in ordinary application logs merely to achieve this. An internal fingerprint can establish whether the content changed without exposing the content itself.
If the request changes, count again or send it through a clearly documented alternative budgeting path. Do not silently attach an old measurement to a new request.
For multi-step workflows, repeat the decision when new tool results or retrieved passages substantially change the next model input.
Reduce input without removing the evidence
When a request exceeds your ceiling, indiscriminately deleting the oldest text is easy to implement and often difficult to trust.
Start by identifying the role of each component. Which instructions define the task? Which passages contain evidence? Which messages merely repeat information already captured elsewhere? Which tool descriptions are irrelevant to the current operation?
A sensible reduction order might remove duplicate passages, unused tool definitions, boilerplate, and redundant history before touching the evidence required to answer the question.
If summarization is part of the reduction process, preserve references to the original material. Otherwise, the application can become smaller while losing the information needed to verify its conclusions.
For evidence-heavy workflows, pair this budgeting design with Treerouter’s Claude citation implementation guide. The two controls serve different purposes: one governs request size; the other helps users inspect the basis of an answer.
Give oversized requests an understandable user experience
A developer can interpret “input limit exceeded.” A business user may only see that an uploaded document did not work.
Your interface should explain the available next step. For example, let the user select sections, narrow the question, remove attachments, or start a document-processing workflow designed for larger inputs.
Do not ask the user to guess an appropriate token count. Translate the application’s decision into an action they understand.
A report-review product might say: “This request includes the entire report and a long conversation. Start a new analysis with the report only, or select the chapters you want reviewed.”
Keep the distinction between an application policy and a provider rejection visible in internal records. A locally rejected request should not appear on your reliability dashboard as a Claude outage.
This separation helps support teams answer questions without blaming the gateway for a decision your own product made.
Plan for an unavailable counting endpoint
Token counting should not become a hidden single point of failure.
Decide what your application does if the endpoint is unavailable, unsupported, or temporarily limited. The right behavior depends on the workflow.
For a large document request close to your ceiling, delaying or declining generation may be appropriate. For a small, tightly bounded prompt, a conservative local estimate may be sufficient as a temporary policy.
Label estimates honestly. Do not display a locally estimated number as a provider-confirmed count.
An unavailable endpoint also does not justify retrying forever. Use a bounded attempt policy and make the resulting state visible to the caller. A counting failure, a generation failure, and an application rejection should remain separate events.
Refer to Claude API errors when interpreting provider responses, and verify how your gateway represents them.
Separate context planning from rate-limit planning
A request can fit inside a model’s context allowance and still exceed the operational capacity available to your application.
Context planning asks whether one request fits. Rate-limit planning asks whether the service can accept the volume and timing of requests you send. Counting calls and generation calls may also have different operational limits.
Read the current Claude rate-limit documentation, then check the conditions of your gateway account. Do not assume that a provider’s published account tier describes the capacity of an intermediary route.
If a team submits many large documents at once, admission control may need both an input-size decision and a queue decision.
Treerouter’s API concurrency planning guide discusses the operational side using GLM. Its model-specific details should stay with GLM, but the distinction between queue capacity and individual request size is useful when designing your own Claude service.
Reconcile estimates with actual usage
After generation, store the usage information returned by the route alongside your preflight measurement.
The objective is to understand differences, not to force both values to match through arbitrary adjustments. Check whether the generated request changed, whether different features were involved, and whether the gateway exposes the relevant usage categories.
A preflight count also does not establish a final monetary charge. Billing can depend on output, applicable usage categories, route pricing, and other features used by the request.
Consult Claude pricing for the provider’s current categories and Treerouter’s usage inspection instructions for account-side records.
For a multi-step application, Treerouter’s agent token-cost guide is a related resource. Keep that broader cost discussion separate from the narrow admission decision implemented here.
Test the boundary before opening the workflow to customers
Use a small acceptance suite rather than one successful demonstration.
Include a short request, a request just below your application ceiling, one above it, a request with additional history, and a request whose model configuration changes. Test the case where counting succeeds but generation never starts, too.
The expected result should be explicit for every case. An oversized request should receive a useful explanation. An unsupported count operation should follow the documented fallback policy. A changed prompt should not reuse an outdated measurement.
Measure the extra latency introduced by preflight checks. If counting every tiny request makes the product unnecessarily slow, consider limiting the check to workflows where input size is variable or consequential.
The final acceptance criterion is operational clarity: your team can explain why a request was sent, reduced, delayed, or rejected.
Try the workflow with your own Claude requests
A meaningful gateway evaluation starts with the request your application will actually send.
Before registering for a trial, prepare one representative prompt, one oversized prompt, and the model capabilities you need. Then use the Treerouter platform and its endpoint configuration guidance to confirm the route.
Ask whether Claude token counting is supported for that account and endpoint. If it is, run the preflight and generation checks together. If it is not, decide whether the documented alternative meets your product’s needs.
The reason to adopt an API gateway is that it makes model access manageable for your application. For long-input Claude workloads, a clear token-budget decision is one concrete way to establish that value before moving production traffic.
