Coding with AI

Which Gemini Token Count Should You Trust?

Count a complete Gemini request before sending it, then match the response usage fields to the right API channel with this practical worksheet.

Clear glass vessel holding colored tiles, with a few tiles beside it, illustrating a token count before and after a request.

Count the complete request with the token counter for your Gemini model before you send it. Then read the completed response’s usage fields. The first number covers input; it cannot tell you how many output or thinking tokens the call used. Google exposes these numbers differently in the Gemini Developer API, Firebase AI Logic, and Gemini Enterprise Agent Platform. A useful record therefore starts with the API channel and model, not a bare number. Google’s token guide describes input-only counting and post-response usage; Firebase’s guide names its response fields separately.

Choose the API channel first

“Gemini” names a model family, not one interchangeable set of SDK calls. Google currently documents an Interactions response with usage for the Gemini Developer API. Firebase AI Logic documents usageMetadata. The Gemini Enterprise Agent Platform guide shows usage_metadata in a Python SDK example. Those names belong to their respective examples. Record the channel, SDK and version, model ID, and operation before comparing two counts. Developer API guide | Firebase guide | Agent Platform guide.

Channel and documented operation Before the request After the response What the preflight number excludes
Gemini Developer API, Interactions in the current guide client.models.count_tokens(...).total_tokens in Python; countTokens(...).totalTokens in JavaScript interaction.usage: total_input_tokens, total_output_tokens, total_thought_tokens, total_cached_tokens, total_tool_use_tokens, total_tokens Output, thinking, and tool use that has not happened yet
Firebase AI Logic, generate response countTokens returns total_tokens for the input usageMetadata: prompt_token_count, candidates_token_count, thoughts_token_count, total_token_count Output and thinking tokens
Gemini Enterprise Agent Platform, Google Gen AI SDK models.count_tokens returns total_tokens in the documented Python example; its SDK also has a local tokenizer for supported models response.usage_metadata in the documented Python generate-content example The generated response and any subsequent thinking

The table follows each product’s published examples, read on November 22, 2026. It is a field map, not a claim that the products use identical request formats or token accounting. The Agent Platform documentation calls its countTokens result an estimate for multimodal input and says actual usage is available in the response’s usage_metadata. It recommends its integrated SDK tokenizer for counting there. Check the supported model and operation before building around any one method. Agent Platform Count Tokens API and local tokenizer guide.

Count the complete next request

Send the same input to the counter that you intend to send for generation: conversation history, the new turn, instructions, tool definitions, and attached content where the API accepts them. Firebase says its prompt count includes text and input files plus system instructions and tools. For chat, it says to append the next turn to the history when counting the size of the next request. Counting only the last user message understates that request. Firebase token counting guide.

Keep a request record with the model ID and a private identifier or hash for the actual payload. Do not log sensitive prompt text merely to collect token statistics. Save the preflight count next to the intended output reservation. If you trim the history or change a system instruction after counting, count again: the previous number describes a different request. This is a practical workflow recommendation, not a claim that Google recalculates your local record.

For a rough first pass, Google says 100 Gemini tokens are about 60 to 80 English words, or around four characters per token. That rule is useful for sizing a draft, but token boundaries depend on the model and content. Code, JSON, other languages, files, and tool schemas are reasons to use the model’s counter when a request is near a limit. Google’s token guide. Our token counter can help you plan from pasted text, but its Gemini rows are estimates based on a different tokenizer, as the tool page states. Do not treat that estimate as a Google countTokens response.

There are limits to the preflight number. Firebase says countTokens reports input tokens, not the number of images or seconds of media. For Agent Platform, Google says the multimodal count is estimated from the chosen media resolution and can differ from consumed tokens. Neither statement gives a universal token charge per image across all Gemini products and models. If your input includes media, keep the file and resolution details with the count and inspect final usage. Firebase guide | Agent Platform Count Tokens API.

Read usage after the response

For a Gemini Developer API Interactions response, the current guide lists total_input_tokens, total_output_tokens, total_thought_tokens, total_cached_tokens, total_tool_use_tokens, and total_tokens under usage. Those are the field names to preserve for that route. In its multi-turn example, the second interaction uses previous_interaction_id, and the guide says its usage includes tokens from both turns. Do not compare that input count with a counter run on only the latest message. Developer API token guide.

In Firebase AI Logic, usageMetadata.prompt_token_count is input, candidates_token_count is output without thinking tokens, thoughts_token_count is thinking, and total_token_count includes input and output including thinking. Its guide says usageMetadata appears only in the last streaming chunk; intermediate chunks have no value. A log collector that saves only an early chunk will miss the usage record. Firebase token counting guide.

The Agent Platform’s published generate-content example prints response.usage_metadata; its sample shows prompt, candidate, cached-content, and total fields. Another example includes a thoughtsTokenCount. These examples are evidence for that SDK path, not a schema promise for every Gemini endpoint. Preserve the object as returned and map its documented fields only after identifying the operation and API version. Agent Platform list and count tokens.

Reconcile the two numbers with a worksheet

Use one row per completed request. This illustrative worksheet uses invented counts to show the method; it is not an API response, a test, or a bill. The first row follows Firebase field names so the arithmetic is visible. Other channels need their own field mapping.

Worksheet field Illustrative value Action
Channel, operation, model Firebase AI Logic; generate response; example model ID Record the exact values from your call
Preflight countTokens.total_tokens 1,200 Save before sending the unchanged full request
Final prompt_token_count 1,204 Compare with preflight input; inspect any changed payload or counting assumptions
Final candidates_token_count 180 Record generated output separately
Final thoughts_token_count 40 Record thinking separately from candidate text
Final total_token_count 1,424 In this invented example, 1,204 + 180 + 40 = 1,424

The four-token difference in this example is a prompt to inspect the request, not proof of a billing error. Did the client add a system instruction, tool definition, history turn, or file between the two calls? Did you compare the same model and route? If the input was unchanged, retain both raw records and consult the API’s documentation for that route. For Agent Platform multimodal input, Google explicitly warns that its preflight count can differ from final consumed usage. Firebase counting scope | Agent Platform multimodal note.

Do not add a cached-token field to the input count merely because both appear in a response. A cache field can describe a subset of input; its presence does not by itself mean extra tokens should be added. Likewise, do not add total_thought_tokens to total_tokens without first checking the channel’s definition of total. The safe ledger stores each documented field and calculates only a relationship that the relevant documentation defines. To understand when cached input can affect cost, read our separate prompt caching guide; this article does not calculate a bill from token counts alone.

Use counts to protect context space

The preflight count helps answer a different question from post-response usage: will the request leave enough room for an answer? Google’s current Developer API guide says Gemini 4 models share a 1,048,576-token context window across input, thinking, and output, while Gemini 3 and 2.5 have separate input and output budgets. It also says a Gemini 4 request whose input plus max_output_tokens exceeds the shared window has its output limit capped to remaining space. Those are model-family rules in that guide; check the specific model information before using a limit in production. Google’s token and context guide.

As an illustrative calculation, if a shared window is 1,048,576 tokens and a complete request counts 1,000,000 input tokens, 48,576 remain before considering any further constraints: 1,048,576 – 1,000,000 = 48,576. A requested 65,536-token answer would not have that much room. The actual response could be shorter, and thinking may consume some of the shared space. For a broader explanation of what fits, see context windows explained. For the relationship between words and rough token planning, see how many tokens is 1,000 words?.

When a local estimate is enough, use it to decide whether a small draft is comfortably below the model’s limit. When a request is close to a limit, includes media or tools, or needs an auditable usage record, use the documented count path for the actual model and then save the final response usage. The count before the call answers “how large is the input I plan to send?” The response record answers “what did this completed call use?” Keep both with the channel and model so the numbers remain interpretable.

Sources

All pages read on November 22, 2026.

Free toolHow many tokens is my prompt?Count my tokens
DailyTech Editorial Team

We explain AI with numbers you can check. Every price, limit and benchmark links to its source and the date we read it. How we work · Report an error