Counting tokens before you send: the token counting APIs agent builders should use

Most agent cost surprises show up after the request already went out. The loop grabbed a big tool result, the history grew past what you planned for, and the bill or the context-length error tells you about it later. The fix is boring: count the input before you send it. All three big model APIs now have an endpoint that takes the same payload you'd send to generate a response and gives back the number of input tokens, without running the model.

This post covers how those endpoints work on Anthropic, OpenAI and Gemini as of November 13, 2026, the gaps worth knowing about, and a simple way to wire a pre-send check into an agent loop. Everything here comes from the linked official docs fetched today, so check them again before you build on a detail.

Why "characters divided by four" stops working in agents

The old trick for estimating tokens was to divide the character count by four. Google's token guide still gives that rule of thumb for Gemini: about four characters per token, with 100 tokens being roughly 60 to 80 English words. For a plain chat prompt that's close enough.

Agents don't send plain prompts. A single request carries a system prompt, a tools array with JSON schemas, earlier turns, tool results, maybe a screenshot or a PDF, and sometimes thinking blocks from earlier turns. OpenAI's token counting guide is blunt about where local estimates break: tokenizers like tiktoken handle plain text, but images and files aren't supported, tools and schemas add tokens that are hard to count locally, and the count includes formatting tokens for message roles and boundaries that never show up in the text you tokenized.

Tokenizers also change between model generations. Anthropic's token counting docs say Claude Opus 4.7 and later models use a newer tokenizer, and the same text produces roughly 30 percent more tokens than on earlier models. The page lists Claude Fable 5.2, Fable 5.1, Fable 5 and the matching Mythos models as sharing that tokenizer, and it tells you not to reuse counts measured on an older model when you estimate costs or context fit after a migration. If your budget math was tuned against an older Claude model, it's probably low now.

Anthropic: /v1/messages/count_tokens

Claude's endpoint is POST /v1/messages/count_tokens. It takes the same structure as a Messages request, including the system prompt, tools, images, PDFs and thinking settings, and returns a single input_tokens number. The docs' own example of a short system prompt plus "Hello, Claude" comes back as 14 tokens. Adding one small get_weather tool pushes their example to 403, which is a good reminder that tool definitions aren't free. Tool use adds its own overhead on top of the schema text you wrote.

Token counting on Claude is free, and its rate limits are separate from message creation, so counting doesn't eat into your generation limits. The docs list 5,000 requests per minute on the Start tier, 10,000 on Build and 20,000 on Scale. The count is labeled an estimate: the real input can differ by a small amount, and Anthropic may add system tokens to the count that you aren't billed for.

The gaps matter for agents. The endpoint returns an invalid_request_error for server tools such as web search, web fetch, code execution and tool search (the advisor tool is the exception), for the MCP connector, and for image or document blocks that point at a url or file source. To count images and PDFs you have to send them base64. For requests that use server tools or MCP servers, you're left reading the usage object on the real response. Counting also ignores prompt caching. You can include cache_control blocks, but the number you get back is the plain input size, not what you'd pay after cache hits. For that side of the math, see our prompt caching comparison.

On thinking: Anthropic notes that thinking blocks from earlier assistant turns count toward input on models that keep all prior turns, while models that keep only the last turn strip them and they don't count. If you're replaying long reasoning traces through a loop, count with the exact model you'll call.

OpenAI: /v1/responses/input_tokens

OpenAI's version is POST /v1/responses/input_tokens, documented in the API reference. It accepts the same input format as responses.create, which means text, messages, images, files, tools, conversations and previous_response_id, and it returns an object with input_tokens. The reference example sends "Tell me a joke." to GPT-6 Astra and gets 11 back.

The guide says the count includes the formatting tokens for request structure, and that files passed by file_id, file_url or file_data are counted as the model's full processed input. That's the main reason to prefer it over tiktoken in an agent: the request you're about to send almost always has tools and structured history in it.

It only counts input, though, and the guide's section on output tokens explains why that's half the picture. Reported output usage includes every token the model generates, including formatting tokens for response channels and tool calls that don't appear in the visible content. So output_tokens can come out higher than the visible text even when reasoning tokens are zero. The guide's advice is to leave headroom in max_output_tokens instead of assuming a fixed gap.

Gemini: countTokens

Gemini's endpoint is models/{model}:countTokens in the Gemini API, exposed as client.models.count_tokens in the Python SDK and countTokens in JavaScript. It returns the total tokens in the input only. After a call, the usage on the response breaks things out further, with fields for input, output, thinking, cached content and tool use.

The Gemini docs are the most useful of the three for media math, because they publish the rules. Images no bigger than 384 pixels in both dimensions count as 258 tokens. Larger images get tiled into 768 by 768 pixel tiles at 258 tokens each. Audio is 32 tokens per second, and video under static processing is 263 tokens per second. Agentic video processing varies and is reported across several usage fields. By that tiling rule, a 1536 by 1536 screenshot works out to four tiles, or 1,032 tokens. A browser agent that grabs a screenshot every step is adding about a thousand tokens per step before any text, and that history piles up.

Putting a count in front of the loop

Here's the pattern that pays for itself. Before each model call, build the exact payload you're about to send, count it, and compare it against two limits you choose: a context ceiling well under the model's window and a per-call spend ceiling. If the payload fits both, send it. If it's over, do something cheaper than finding out the hard way, like compacting the history, trimming an oversized tool result, or routing the call to a smaller model.

The cost math is plain multiplication against the input price. Using the prices in our model data as of today, Claude Opus 5.5 input is $4 per million tokens, so a 60,000-token payload costs $0.24 in input before any output. On Claude Fable 5.2 at $8 per million, a 200,000-token payload is $1.60 in input for that single call. At GPT-6 Luna's $0.10 per million, the same 200,000 tokens is $0.02. Multiply any of these by the number of turns and you can see why a quick count is worth more than one more guess. Our post on budget caps for agent runs covers what to do once a run actually crosses the line.

A few habits keep the numbers honest. Count with the model ID you'll actually call, since tokenizers differ by generation. Don't double-count, because the count is a separate request from generation, and on Claude it's explicitly free with its own rate limit. For anything the endpoint refuses, like Claude server tools, MCP connectors or url-sourced files, fall back to logging usage from real responses and keeping a running average per tool. And treat the count as input only. Output, including hidden formatting and reasoning tokens, still needs its own cap.

If you want the bigger picture on running models in production, cost tradeoffs included, AI Engineering by Chip Huyen is a solid book to keep around.

The short version

All three providers will count a full request for you without running it. Anthropic's count_tokens and OpenAI's responses/input_tokens accept the same payload as generation and include tool and structure overhead. Gemini's countTokens does the same and publishes its image, audio and video rates. The parts they won't do for you are counting output, applying cache discounts, and (on Claude) counting server tools and MCP. Put a count in front of every call, compare it to a budget you picked on purpose, and you'll catch the runaway turn before it reaches the bill.