Interactions API

The Interactions API is the new standard primitive for building with Gemini, recommended for all new projects. It is optimized for agentic workflows, server-side state management, and complex multi-modal, multi-turn conversations. The original generateContent API remains fully supported.

Why use the Interactions API?

  • Server-side history management: Simplified multi-turn flows via previous_interaction_id. The server enables state by default (store=true), but you can opt into stateless behavior by setting store=false.
  • Observable execution steps: Typed steps make it easy to debug complex flows and render UI for intermediate events (like thoughts or search widgets).
  • Built for agentic workflows: Native support for multi-step tool use, orchestration, and complex reasoning flows through typed execution steps.
  • Long-running and background tasks: Supports offloading time-intensive operations like Deep Think and Deep Research to background processes using background=true.
  • Access to new models and capabilities: Going forward, new models beyond the core mainline family, along with new agentic capabilities and tools, will launch exclusively on the Interactions API.

Use the Interactions API if you're starting a new project, building agentic applications, or need server-side conversation management. Use generateContent if you have an existing integration that works for your needs, or if you require a feature that is not yet available in the Interactions API, such as the Batch API or explicit caching.

Get started

  • Set up your coding agent: Connect to the Gemini Docs MCP and install the gemini-interactions-api skill to give your assistant direct access to the latest developer docs and best practices. Set up your coding agent →
  • Migrate from generateContent: If you have an existing integration, follow the Migration Guide to transition to the Interactions API.
  • Try the quickstart: Get started with a minimal working example in the Interactions API quickstart.

Feature Guides

Explore the specific capabilities of the Interactions API through these guides. You can use the toggle on these pages to switch between generateContent and Interactions API:

How the Interactions API works

The Interactions API centers around a core resource: the Interaction. An Interaction represents a complete turn in a conversation or task. It acts as a session record, containing the entire history of an interaction as a chronological sequence of execution steps. These steps include model thoughts, server-side or client-side tool calls and results (like function_call and function_result), and the final model_output. The stored resource (retrieved via interactions.get) also includes user_input steps for full context, though the interactions.create response only returns model-generated steps.

When you make a call to interactions.create, you are creating a new Interaction resource.

Server-side state management

You can use the id of a completed interaction in a subsequent call using the previous_interaction_id parameter to continue the conversation. The server uses this ID to retrieve the conversation history, saving you from having to resend the entire chat history.

The previous_interaction_id parameter preserves only the conversation history (inputs and outputs) using previous_interaction_id. The other parameters are interaction-scoped and apply only to the specific interaction you are currently generating:

  • tools
  • system_instruction
  • generation_config (including thinking_level, temperature, etc.)

This means you must re-specify these parameters in each new interaction if you want them to apply. This server-side state management is optional; you can also operate in stateless mode by sending the full conversation history in each request.

Data storage and retention

By default, the API stores all Interaction objects (store=true) in order to simplify use of server-side state management features (with previous_interaction_id), background execution (using background=true) and observability purposes.

  • Paid Tier: The system retains interactions for 55 days.
  • Free Tier: The system retains interactions for 1 day.

If you don't want this, you can set store=false in your request. This control is separate from state management; you can opt out of storage for any interaction. However, note that store=false is incompatible with background=true and prevents using previous_interaction_id for subsequent turns.

You can delete stored interactions at any time using the delete method found in the API Reference. You can only delete interactions if you know the interaction ID.

After the retention period expires, your data will be deleted automatically.

The system processes Interaction objects according to the terms.

Best practices

  • Cache hit rate: Using previous_interaction_id to continue conversations allows the system to more easily utilize implicit caching for the conversation history, which improves performance and reduces costs.
  • Mixing interactions: You have the flexibility to mix and match Agent and Model interactions within a conversation. For example, you can use a specialized agent, like the Deep Research agent, for initial data collection, and then use a standard Gemini model for follow-up tasks such as summarizing or reformatting, linking these steps with the previous_interaction_id.

Supported models & agents

Model Name Type Model ID
Gemini 3.1 Flash-Lite Model gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite Preview Model gemini-3.1-flash-lite-preview
Gemini 3.1 Pro Preview Model gemini-3.1-pro-preview
Gemini 3 Flash Preview Model gemini-3-flash-preview
Gemini 2.5 Pro Model gemini-2.5-pro
Gemini 2.5 Flash Model gemini-2.5-flash
Gemini 2.5 Flash-lite Model gemini-2.5-flash-lite
Lyria 3 Clip Preview Model lyria-3-clip-preview
Lyria 3 Pro Preview Model lyria-3-pro-preview
Deep Research Preview Agent deep-research-pro-preview-12-2025
Deep Research Preview Agent deep-research-preview-04-2026
Deep Research Preview Agent deep-research-max-preview-04-2026

SDKs

You can use latest version of the Google GenAI SDKs in order to access Interactions API.

  • On Python, this is google-genai package from 1.55.0 version onwards.
  • On JavaScript, this is @google/genai package from 1.33.0 version onwards.

You can learn more about how to install the SDKs on Libraries page.

Limitations

  • Beta status: The Interactions API is in beta/preview. Features and schemas may change.
  • Remote MCP: Gemini 3 does not support remote MCP, this is coming soon.

The following features are supported by the generateContent API but are not yet available in the Interactions API:

Breaking changes

The Interactions API is currently in an early beta stage. We are actively developing and refining the API capabilities, resource schemas, and SDK interfaces based on real-world usage and developer feedback.

As a result, breaking changes may occur. Updates may include changes to:

  • Schemas for input and output.
  • SDK method signatures and object structures.
  • Specific feature behaviors.

For production workloads, you should continue to use the standard generateContent API. It remains the recommended path for stable deployments, and we will continue to actively develop and maintain it.

Feedback

Your feedback is critical to the development of the Interactions API. Share your thoughts, report bugs, or request features on our Google AI Developer Community Forum.

What's next