Skip to content

The Gemini API: Interactions, Pricing, and Rate Limits Explained

What the Interactions API actually manages for you, what Gemini 3.8 Flash costs on the free and paid tiers, and how rate limits and usage tiers work.

CurrentLast verified

Platforms

  • Gemini API (Python, JavaScript, Java, REST)

What the official documentation says

  • The Interactions API is built around a core resource, the Interaction, which represents a complete turn — a session record containing the entire history as a chronological sequence of execution steps such as model thoughts, tool calls and results, and the final model output.

    Interactions API overview

  • You can continue a conversation by passing the id of a completed interaction as previous_interaction_id in a later call; the server retrieves the history so you don't have to resend it. This server-side state is optional — you can operate statelessly by resending the full history yourself.

    Interactions API overview

  • previous_interaction_id preserves only conversation history; parameters like tools, system_instruction, and generation_config are interaction-scoped and must be re-specified on every new interaction if you want them to keep applying.

    Interactions API overview

  • By default the API stores Interaction objects (store=true) to support server-side state, background execution, and observability; you can opt out per request with store=false.

    Interactions API overview

  • Stored interactions are retained for 55 days on the paid tier and 1 day on the free tier.

    Interactions API overview

  • There are three pricing plans — Free, Paid, and Enterprise. Paid unlocks higher rate limits, context caching, the Batch API (a 50% cost reduction), access to Google's most advanced models, and content is not used to improve Google's products; Free content may be used to improve Google's products.

    Gemini API pricing

  • For Gemini 3.8 Flash on the standard (non-batch) paid tier, input is $0.75 per 1M tokens and output (including thinking tokens) is $3.75 per 1M tokens through December 31, 2026, rising to $1.50 and $7.50 respectively starting January 1, 2027.

    Gemini API pricing

  • Grounding with Google Search on the paid tier includes 5,000 free search requests per month shared across all Gemini 3.x models, then $14 per 1,000 requests; Grounding with Google Maps follows the same 5,000-free-then-$14-per-1,000 structure.

    Gemini API pricing

  • The Batch API on the paid tier is priced at roughly half the standard tier for Gemini 3.8 Flash ($0.375 input / $1.875 output per 1M tokens through December 31, 2026).

    Gemini API pricing

  • Rate limits are measured across three dimensions — requests per minute (RPM), tokens per minute (TPM), and requests per day (RPD) — applied per project, not per API key; exceeding any one of them triggers a rate limit error even if the others are not exceeded.

    Gemini API rate limits

  • Requests per day (RPD) quotas reset at midnight Pacific time; rate limits are more restricted for experimental and preview models.

    Gemini API rate limits

  • The Gemini API also enforces spend-based rate limits, evaluated on a rolling 10-minute window; Tier 1 is capped at $10 per 10 minutes, Tier 2 at $50, and Tier 3 at $200. Exceeding one returns a 429 RESOURCE_EXHAUSTED error.

    Gemini API rate limits

  • Usage tiers upgrade automatically as spend and account history grow — Tier 1 requires linking an active billing account (billing tier cap $250), Tier 2 requires $100 paid plus 3 days since first successful payment (cap $2,000), and Tier 3 requires $1,000 paid plus 30 days since first successful payment (cap $20,000-$100,000+).

    Gemini API rate limits

The Interaction is the unit everything is built from

The Interactions API centers on one resource: the Interaction. It's a session record for one complete turn, holding a chronological list of execution steps — the model's thinking, any tool calls and their results, and the final output. When you call interactions.create, you're creating one of these.

The useful part for multi-turn features is previous_interaction_id: pass the id of a completed interaction, and the server retrieves that history for you instead of you resending the whole conversation. This is optional server-side state — you can still manage history yourself and operate statelessly if you prefer.

One detail worth internalizing early: previous_interaction_id only carries forward conversation history. Parameters like tools, system_instruction, and generation_config are scoped to the specific interaction you're creating — leave them off a follow-up call and they don't apply, even if you set them on the first turn.

Storage and retention are opt-out, not opt-in

By default, the API stores every Interaction object (store=true), which is what makes previous_interaction_id, background execution, and observability work without extra setup. You can set store=false per request if you don't want that.

If you do rely on storage, know the retention window: 55 days on the paid tier, 1 day on the free tier. Don't design a feature that assumes an interaction is retrievable next month unless you're also persisting it somewhere yourself.

What Gemini 3.8 Flash actually costs

Three plans exist — Free, Paid, and Enterprise. Paid is where production traffic belongs: higher rate limits, context caching, the Batch API at roughly half price, access to the most advanced models, and — a real distinction, not just marketing — content is not used to improve Google's products, unlike the free tier.

For Gemini 3.8 Flash on the standard paid tier, current pricing (through the end of 2026) is:

| | Free tier | Paid tier, per 1M tokens | |---|---|---| | Input | Free | $0.75 | | Output (incl. thinking tokens) | Free | $3.75 | | Grounding: Google Search | Not available | 5,000 free requests/month (shared across Gemini 3.x), then $14/1,000 | | Grounding: Google Maps | Not available | 5,000 free/month, then $14/1,000 |

Prices roughly double starting January 1, 2027 ($1.50 input / $7.50 output). If your workload can tolerate async processing, the Batch API runs at about half the standard price — $0.375 input / $1.875 output per 1M tokens through 2026.

Budget for grounding separately from tokens. It's easy to price out the model call and forget that Google Search and Google Maps grounding both have their own free allowance and per-1,000-request charge once you're past it.

Rate limits: three request dimensions, plus spend

Rate limits apply per project, not per API key, across three measurements: requests per minute (RPM), tokens per minute (TPM), and requests per day (RPD, resetting at midnight Pacific time). Hitting any single one triggers a rate-limit error, independent of the other two — a 20 RPM cap means request #21 in one minute fails even with plenty of TPM headroom left.

On top of that, there's a separate spend-based rate limit, evaluated on a rolling 10-minute window, that applies depending on your billing history:

| Usage tier | Spend limit per 10 minutes | |---|---| | Free | N/A | | Tier 1 | $10 | | Tier 2 | $50 | | Tier 3 | $200 |

Both kinds of limit return the same 429 RESOURCE_EXHAUSTED error, which is exactly why it's worth knowing which one you actually hit before you decide how to fix it — request throttling and spend throttling call for different responses.

How usage tiers upgrade

Tiers move up automatically based on cumulative Google Cloud billing spend, not manual approval in the normal case:

  • Tier 1 — link an active billing account (cap $250)
  • Tier 2 — $100 paid, 3+ days since your first successful payment (cap $2,000)
  • Tier 3 — $1,000 paid, 30+ days since your first successful payment (cap $20,000–$100,000+)

From here, the practical next steps are Google AI Studio for prototyping before you spend anything, or function calling and tools once a plain text-in-text-out interaction isn't enough.

How to do it

  1. Decide whether a feature needs server-side history (previous_interaction_id, the default store=true) or should run statelessly (store=false, resending history yourself).
  2. If using previous_interaction_id, re-specify tools, system_instruction, and generation_config on every new call — they are not carried forward automatically.
  3. Estimate cost from the Gemini 3.8 Flash pricing table ($0.75/1M input, $3.75/1M output through 2026) and check whether Batch API's roughly half-price rate fits your workload.
  4. Check which usage tier your project qualifies for based on billing account status and payment history, since that determines your RPM/TPM/RPD and spend-based caps.
  5. When you hit a 429, check RPM, TPM, RPD, and the rolling 10-minute spend limit separately — any one of them alone can trigger the error.

On Windows

N/AThe Interactions API, pricing, and rate limits apply identically regardless of operating system.

On mobile

N/AThis tutorial covers API mechanics and billing, not a mobile client.

Use cases

  • Estimating monthly cost for a Gemini 3.8 Flash integration before committing to the paid tier.
  • Designing a multi-turn feature and deciding whether to use previous_interaction_id or manage history yourself.
  • Diagnosing a 429 error by checking whether it's a request-rate limit, a token-rate limit, or a spend-based limit.

Common mistakes

  • Assuming previous_interaction_id also replays tool configuration or system instructions from the earlier turn. It only preserves conversation history — interaction-scoped parameters must be resent every time.
  • Not realizing free-tier content may be used to improve Google's products, while paid-tier content is not — a real consideration for anything handling non-public data.
  • Budgeting only for token price and forgetting Grounding with Google Search and Google Maps are billed separately once the 5,000-free-request monthly allowance (shared across Gemini 3.x models) is used up.
  • Treating all 429 errors as the same request-rate problem. A spend-based rate limit produces the identical 429 RESOURCE_EXHAUSTED error but needs a different fix — slowing spend, not just retrying.
  • Expecting a stored interaction to be retrievable indefinitely. Free-tier retention is 1 day; even paid-tier retention is 55 days, not forever.

FAQ

What exactly does an Interaction contain?
The full execution history of one turn — model thoughts, tool calls and their results, and the final model output — addressable by an id you can retrieve later or pass forward as previous_interaction_id.
Do I have to let Google store my interactions?
No. Storage is on by default (store=true) to enable state management, background execution, and observability, but you can set store=false per request to opt out.
How much does Gemini 3.8 Flash cost?
On the paid standard tier, $0.75 per 1M input tokens and $3.75 per 1M output tokens (including thinking tokens) through the end of 2026, with prices doubling on January 1, 2027. The free tier has no token charge but more limited access.
Why did I get a 429 error even though I'm under my request-per-minute limit?
Rate limiting isn't just RPM. It can also be a tokens-per-minute limit, a requests-per-day limit, or — separately — a spend-based limit evaluated over a rolling 10-minute window if your usage tier has one.
How do I get a higher usage tier?
Tiers upgrade automatically based on cumulative Google Cloud billing spend and account history — Tier 1 needs a linked billing account, Tier 2 needs $100 paid and 3 days since your first successful payment, Tier 3 needs $1,000 paid and 30 days since your first successful payment.

Official sources

These are the pages this tutorial is checked against. Follow them if you need the vendor's exact wording.

Source status