Gemini Token Counts: Estimate Inputs and Check Actual Usage
A token count before a request estimates its input, while usage after the response records what the API reports. Read both and check pricing terms rather than calculating from word counts alone.

Distinguish the token count before a request from usage after the response
countTokens counts tokens in data prepared for model input before requesting generation. The data usage reported after requests helps check actual input/output tokens and additional usage units for some capabilities. Documentation Gemini token counting explains both periods separately
When using GenerateContent API Check usageMetadata For example promptTokenCount, candidatesTokenCount and thoughtsTokenCount When present, the Interactions API Use interaction.usage Current documentation examples use different field names and scopes across SDKs. Follow the actual endpoint/version and do not double-count totals and their components.
Tokens are processing units for text and other inputs, not a fixed number of Thai words or characters. Images, audio, video, system instructions, and tool descriptions may also count. Do not estimate actual costs using “one word equals one token.”
| Data | When to use it | What it indicates |
|---|---|---|
| countTokens | before calling the model | Input quantity according to counted request format |
| usage after answering | After receiving results | Quantity of inputs, outputs, and items reported by the API. |
| Pricing/Billing | During assessment and balance reconciliation | Actual rates and terms by model, plan, and capability |
A measurement method that separates costs from guesswork
Google’s example separates count_tokens before the request from interaction.usage after the response.
# This will only work for SDK newer than 2.0.0
from google import genai
client = genai.Client()
prompt = "The quick brown fox jumps over the lazy dog."
# Count tokens before sending
total_tokens = client.models.count_tokens(
model="gemini-3.8-flash",
contents=prompt,
)
print('total_tokens:', total_tokens.total_tokens)
# Get usage from interaction
interaction = client.interactions.create(
model="gemini-3.8-flash",
input=prompt,
)
print(interaction.usage)
The documentation specifies an SDK newer than 2.0.0. This example uses Interactions API to generate the response; GenerateContent API fields may differ. We have not run it or validated the named model. Source: Source documentation · Apache-2.0 / CC BY 4.0
- Choose the model first: Use the same model for counting and generation, since tokenization and prices may differ
- Complete the inputs: Include system instructions, resent history, documents, and relevant tool settings, not just the latest user message.
- Count before sending: Use countTokens from the current SDK/API to estimate request size and check context limits
- Read usage after the response: Record input, output, and additional fields actually returned by the API, without assuming every field exists in every version.
- Apply the appropriate rate to each category: Check pages Gemini Developer API pricing of the model and tiers used, and include additional tools and other items when relevant.
For multi-turn conversations, check whether new requests resend history or how state is managed. Counting only the latest one-line question may substantially understate usage, especially with long documents or repeated system instructions.
Hypothetical example: 8,000 input tokens and total cost
Suppose a request contains 8,000 input tokens and produces 2,000 output tokens. Assume rates of $0.50 per million input tokens and $2 per million output tokens. These figures illustrate the formula; they are not Google prices at the time of writing. 8,000 Token and the model responds with output counted in the example 2,000 Token Set the input assumed rate. 0.50 Dollars per 1 Million Tokens and output 2 dollars per 1 million tokens This number was created to teach the formula. not Google's prices at the time of writing
- Input = 8,000 ÷ 1,000,000 × 0.50 = 0.004 Dollars
- Output = 2,000 ÷ 1,000,000 × 2 = 0.004 Dollars
- Total for the two components = $0.008 per request under these assumptions. 0.008 Dollars per request Under this assumption
For 500 requests with identical usage, the two cost components total 500 × 0.008 = 4 dollars before other fees, credits, taxes, or hosting. Use the calculation as a budget estimate, then reconcile it with the actual bill.
Why actual figures may differ from the examples
Usage and costs may differ because of added history or files, longer answers, thinking or tool tokens reported by some models, and rates varying by data type, caching, or additional capabilities. Google also notes that system instructions and tool descriptions affect token counts.
Context limits are not spending limits. Requests within the context window can still incur charges, and smaller token counts do not rule out other pricing components. Check actual usage and billing settings. Requests in the context window are not free. And requests that count less tokens doesn't mean there won't be other pricing items. If you need to control costs Check both actual usage amount and billing account settings.
Count each usage category before applying prices
For development, use countTokens to check input size before sending, then read usage from actual responses to refine averages. Compare this with the chosen model's latest prices and terms for a fuller cost estimate than word counts or a single per-million-token rate.
Sources
- Google AI for Developers: Understand and count tokens
- Google AI for Developers: models.countTokens reference
- Google AI for Developers: Gemini Developer API pricing
- Google: GenerateContent UsageMetadata
- Google: source document
Google documentation reviewed October 18, 2026 (Thailand time). No actual Gemini API calls were made. Example token counts and dollar rates illustrate formulas; they are not Google prices, test results, or bills.