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.

Paper pieces pass through a counting tray before processing and a reconciliation tray after results are obtained.

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.”

DataWhen to use itWhat it indicates
countTokensbefore calling the modelInput quantity according to counted request format
usage after answeringAfter receiving resultsQuantity of inputs, outputs, and items reported by the API.
Pricing/BillingDuring assessment and balance reconciliationActual 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

  1. Choose the model first: Use the same model for counting and generation, since tokenization and prices may differ
  2. Complete the inputs: Include system instructions, resent history, documents, and relevant tool settings, not just the latest user message.
  3. Count before sending: Use countTokens from the current SDK/API to estimate request size and check context limits
  4. Read usage after the response: Record input, output, and additional fields actually returned by the API, without assuming every field exists in every version.
  5. 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

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.

Read moreWho pays for an app built with Google AI Studio?Understand AI-call costs, hosting costs, and account entitlements separately

Sources

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.