The count_tokens Endpoint: Checking Request Size Before You Pay for It

A Dedicated Endpoint for Measuring, Not Generating

count_tokens is a separate endpoint that accepts the same request body you would send to a real Messages API call -- model, messages, system, tools, everything -- and returns the token count that request would consume, without running inference. No completion is generated, no output tokens are billed; you get back a number.

count = client.messages.count_tokens(
    model="claude-sonnet-4-5",
    system=LONG_POLICY_DOCUMENT,
    tools=tools,
    messages=messages,
)
print(count.input_tokens)  # exact input-token cost of this exact request, zero inference cost

if count.input_tokens > TOKEN_BUDGET:
    # Gate the request before it's sent, rather than discovering the overrun
    # from a validation error or a model_context_window_exceeded stop_reason.
    messages = compact(messages)

Why This Matters Beyond Curiosity

Because the request body passed to count_tokens is identical in shape to a real call -- same tools, same system prompt, same conversation history -- the count it returns reflects exactly what that specific request would cost on input, including the token weight of tool definitions and any images or documents in the payload. That makes it useful in two different phases of the same problem:

• During development, run it against real production-shaped inputs (not just short test fixtures) to verify your context-budget assumptions actually hold. A budget that looks comfortable against an 800-token test fixture can be wildly wrong against a 3,200-token production tool result -- the kind of gap that turns a clean twenty-turn test session into a session that hits its ceiling at turn eight in production.
• In production, call it as a pre-flight gate before an expensive or context-sensitive call goes out, so a request that would overflow the context window (or blow a cost budget) is caught and handled -- compacted, trimmed, or rejected -- *before* you pay for a wasted or truncated call, rather than discovering the overrun only after the model returns a model_context_window_exceeded stop reason.

Common exam traps

• Assuming you have to send a real (billed) request just to find out how many tokens something costs -- count_tokens answers that question for free, with the exact same request shape.
• Forgetting that count_tokens reflects the *whole* request -- system prompt, tools, and message history all included -- not just the size of the latest user message.
• Treating token counting as a nice-to-have dev-time diagnostic only, rather than a production gate that prevents a request from being sent at all when it would exceed budget.