Claude Token Counter: Count Tokens Exactly With the count_tokens API (and Budget Twitter (X) Data)

Anthropic ships an official token counting endpoint in the Messages API: POST https://api.anthropic.com/v1/messages/count_tokens. Anthropic's docs describe it as a way to "determine the number of tokens in a message before you send it to Claude", and list three uses: managing rate limits and costs, making model routing decisions, and fitting a prompt to a target length.

The request body is the same structured input you would send to https://api.anthropic.com/v1/messages: a model, an optional system prompt, the messages array, and optionally tools and thinking settings. The response has one field, input_tokens. There is no output count, because output tokens do not exist until Claude writes them.

It is an estimate, a precise one. The docs say "the actual number of input tokens used when creating a message might differ by a small amount." They also note that the count can include tokens Anthropic adds automatically for system optimizations, and that you are not billed for those system-added tokens. Billing reflects only your content.

It is model-specific. The endpoint counts under the tokenizer of the model you pass. Pass the exact model ID you will use for inference, not a cheaper sibling, or the number will not match your bill.

It is on every platform Anthropic lists. The token counting page marks the feature stable on the Claude API, Amazon Bedrock, Claude Platform on AWS, Claude models on Google Cloud and Microsoft Foundry, and says all active models support it. It is not available inside Managed Agents.

You need an Anthropic API key (see our Claude API key guide). The cURL example below is Anthropic's own documentation example; it returns {"input_tokens": 14} for a two-word user message plus a short system prompt.

In Python, the official anthropic SDK exposes the same endpoint as client.messages.count_tokens(). In TypeScript it is client.messages.countTokens(). Anthropic's command-line tool has ant messages count-tokens with --model, --system and --message flags. All three call the same endpoint, so the count is identical.

Count the whole request, not just the user text. The quickest way to get a wrong budget is to count only the question. A long system prompt, a dozen tool schemas and a conversation history usually outweigh the new user turn. Build the request object once, pass it to count_tokens, then pass the very same object to messages.create.

Read the billed number afterwards. The usage.input_tokens field on the real Messages response is what you pay for. Log both numbers for a while; if they drift apart by more than a few tokens, something in your request differs between the two calls (a timestamp in the system prompt is the usual cause).

Anthropic's docs list what the endpoint accepts and what it rejects. The table below summarizes them; everything in it comes from the token counting page and the pricing page.

Tools carry a hidden system prompt. Anthropic's pricing page explains that when you send tools, the API adds a tool-use system prompt whose size depends on the model and on tool_choice. The table there lists 286 tokens for Claude Opus 5.5 and Claude Sonnet 5.5 with tool_choice auto or none, versus 675 for Claude Opus 4.7. That is on top of your own tool definitions, and count_tokens includes it, which is a good reason to count with tools attached rather than adding numbers by hand.

Server tools and MCP are counted after the fact. For requests that use server tools or the MCP connector, the docs point you to the usage object on the real Messages response. Server tools can also carry their own usage-based charges (the pricing page gives web search as an example), which no token count will show.

Prompt caching is ignored. The docs' FAQ says token counting "provides an estimate without using caching logic"; you may include cache_control blocks, but caching only happens on real message creation. So count_tokens tells you how big the prompt is, not how much of it will be billed at the cache-read rate.

Yes. Anthropic's token counting page states that token counting "is free to use but subject to requests per minute rate limits based on your usage tier." The published limits are below; the docs add that counting and message creation have separate, independent limits, so counting every request before you send it does not eat into your Messages quota.

Higher limits are requested from the Rate limits page of the Claude Console (the docs call the button Request tier increase).

Free does not mean zero latency. Each count is a network round trip. For a chat app that counts every turn, that is one extra request per turn. A common pattern is to count only when a conversation is likely to approach a limit (for example, once a running estimate passes half the context window), or to count a template once and add the variable part.

Several browser-based "Claude token counter" pages in today's search results label their numbers as estimates. A tokenizer often used for such estimates, tiktoken, describes itself in its own README as "a fast BPE tokeniser for use with OpenAI's models". It encodes text the way OpenAI's models do, so applying it to Claude gives a different number. Anthropic's docs point to the count_tokens endpoint, called with the model you plan to use, as the way to get exact counts.

Anthropic's glossary gives the only official rule of thumb: on models before Claude 4.7 a token represents approximately 3.5 English characters, and Claude 4.7 and later models (and Claude Mythos Preview) use a newer tokenizer that produces approximately 30 percent more tokens for the same text. The glossary also says the characters per token depend on the model and the language, and tells you to use token counting for exact numbers.

Use the rule for budgeting, never for limits. A ratio is fine for a back-of-the-envelope estimate of a monthly bill. It is not fine for deciding whether a prompt fits in a context window or under a rate limit, because code, URLs, emoji and non-English text tokenize very differently from English prose.

Tweets are not average English. In our sample, 51.6% of posts carried a link, and posts mix in handles, hashtags and emoji. Those are exactly the strings where a characters-per-token rule drifts most, which is why the study below reports characters and words as measured facts and labels every token figure as an estimate.

Anthropic's docs are explicit that the same input produces different counts on different models. Claude Opus 4.7 introduced a newer tokenizer; Claude Fable 5.2, Fable 5.1, Fable 5 and the matching Mythos models share it, and a prompt counts the same on all of them, "roughly 30 percent higher than on models before Claude Opus 4.7 (the exact increase depends on the content)."

The docs' advice for migrations is to count the same request once with your current model and once with the model you plan to move to, then compare the two input_tokens values, and not to reuse token counts measured on an older model to estimate cost or context window fit. The script below does exactly that for one prompt file across several model IDs.

Per-token price and token count move together. A model with a lower per-token price can still cost more for the same text if it produces more tokens. Comparing models on price per million tokens alone hides this; compare on counted tokens times price.

Context windows are measured in the same tokens. Anthropic's pricing page says Claude 4.6 and later models (except Haiku 5.5) include the full 1M token context window at standard pricing. A prompt that fit comfortably on an older model can land closer to a limit after a tokenizer change, so recount long documents too.

Input cost is input_tokens / 1,000,000 x base input price per MTok. Output cost uses the output price and the usage.output_tokens you get back; you can cap it with max_tokens but not count it in advance. Base prices from Anthropic's pricing page for the current models:

Three adjustments the formula needs. Cache reads are billed at a fraction of base input (0.05x on Opus 5.5 and Sonnet 5.5 per the pricing page), and cache writes at a premium, which count_tokens cannot see. The Batch API halves both input and output prices. And Haiku 5.5 is priced by prompt length per request, so the count of each individual request decides which row applies.

Our Claude API pricing guide has the full table, including Fable models, fast mode and caching multipliers, plus a model-by-model cost per 1,000 tweets. Use this page's counter code to get the token number and that page to price it.

To ground the formula in real input, we pulled 1,640 recent posts from 12 organization accounts (@AnthropicAI, @claudeai, @OpenAI, @GoogleDeepMind, @github, @vercel, @NASA, @nytimes, @espn, @Reuters, @nvidia and @Docker) with the TwitterAPI.io /twitter/user/last_tweets endpoint, collected in 2026. We measured characters and words of each post's text, and the size of the full JSON object the API returns. We did not have an Anthropic key for this study, so no number below is a measured Claude token count.

The text is short. The median post is 192.5 characters and 28 words; the 90th percentile is 314 characters and the longest post in the sample ran to 1,934 characters. 21.9% of posts were longer than 280 characters, so a "280 characters per tweet" budget undercounts.

The object around it is not. A raw tweet object (author profile, entities, media variants, card data, counts) had a median of 6,344 characters. Compared with a trimmed one-line format (handle, timestamp, text, like / repost / reply / view counts), the raw object was a median 23.4x larger per post (10th percentile 9.6x, 90th percentile 78.4x), and 26.0x larger across the whole sample.

News accounts with link cards (@Reuters, @nytimes) and long-form posters (@AnthropicAI) had the heaviest objects; the raw size is driven by attached metadata, not by how much the account writes.

Per 1,000 tweets, the trimmed format came to 313,146 characters and the raw JSON to 8,153,310 characters (measured). Applying Anthropic's glossary ratio (3.5 English characters per token before Claude 4.7, about 30 percent more tokens on 4.7 and later) gives the estimates below. They are a labeled formula, not counts: run count_tokens on your own prompt before you rely on them.

Trim before you count. The single largest saving in the table is not the model choice but the format: about 26x fewer characters for the same tweets. An estimated 3 million tokens of raw JSON per 1,000 tweets would not even fit in one 1M-token context window; the trimmed version fits comfortably.

Text length has a long tail. 21.9% of posts ran past 280 characters (the histogram below), so budget on a measured average, not on the classic tweet limit. Media matters too: 20.5% of posts carried a photo and 25.6% a video; if you pass images to Claude, they are counted as image tokens on top of the text (send them as base64 so count_tokens can see them).

The data side of the bill. Fetching the tweets themselves on TwitterAPI.io is $0.15 per 1,000 tweets returned (15 credits per tweet); the official X API pay-per-usage rate card on docs.x.com lists $0.005 per post read, which is $5 per 1,000 posts, about 33x more. With a trimmed format, the Claude side and the data side of a 1,000-tweet summary are the same order of magnitude.

Question. How much text, and how much surrounding JSON, does a typical post contain when you fetch it to feed to Claude?

Accounts and endpoint. 12 public organization accounts: @AnthropicAI, @claudeai, @OpenAI, @GoogleDeepMind, @github, @vercel, @NASA, @nytimes, @espn, @Reuters, @nvidia and @Docker. One endpoint, /twitter/user/last_tweets (default, replies excluded), newest first, up to 8 pages of 20 per account. The @GoogleDeepMind and @github timelines ended early (20 and 40 posts), so @nvidia and @Docker were added during collection; @nvidia returned 140 unique posts.

Window and size. The most recent posts of each account at collection time, collected in 2026: 1,640 unique posts from 83 requests, costing about $0.25 at 15 credits per tweet returned.

Metrics. Characters (Python string length) and whitespace-separated words of text; presence of links, photos, videos, quotes and reposts; characters of the compact JSON serialization of each tweet object; characters of a trimmed one-line format. Token and cost figures are derived with Anthropic's published ratio and are labeled as estimates.

What the sample cannot show. It measures organization accounts, which post more links and media than most individuals; replies and private accounts are excluded. It does not measure Claude tokens: we had no Anthropic key, and the characters-per-token ratio for handles, URLs and emoji can differ from English prose. Run count_tokens on your own data for real numbers.

Privacy. Aggregates only, organization accounts only; no analysis of reposted or quoted authors; the published sample file holds de-identified rows (no IDs, URLs, text or handles of individuals).