Repository Public
1The Interactions API is the best way to build with Gemini models2and agents. As of June 2026, it is Generally Available and recommended for all3new projects. While it is now considered legacy, the original4[`generateContent`](https://ai.google.dev/gemini-api/docs/generate-content/text-generation) API5remains fully supported.67## Why use the Interactions API?89- **Universal interface for all applications**: Designed as the standard interface for every use case, including single-turn text generation, multimodal understanding, structured outputs, tool orchestration, and agentic workflows.10- **Single API for models and agents**: One unified endpoint and pattern for calling standard Gemini models as well as specialized agents directly (such as Deep Research and custom managed agents).11- **New capabilities out of the box** : Features like optional server-side conversation state using `previous_interaction_id`, observable execution steps for debugging and UI rendering, and [background12 execution](https://ai.google.dev/gemini-api/docs/background-execution) for long-running tasks using `background=true`.13- **Lower cost with higher cache hit rates**: When using multi-turn conversations, optional server-side state management enables more efficient context caching across turns, reducing token costs.14- **Where new features launch**: Going forward, all new models, multimodal capabilities, tools, and agentic features will launch on the Interactions API.1516By default, the Interactions API stores requests so you can leverage17the server-side state management features by using18`previous_interaction_id`. You can opt into stateless behavior by setting19`store=false`. See the [data retention](https://ai.google.dev/gemini-api/docs/interactions-overview#data-storage-retention) section for20details.2122## Get started2324- **Set up your coding agent** : Connect to the **Gemini Docs MCP** and install the `gemini-api-dev` skill to give your assistant direct access to the latest developer docs and best practices. For detailed steps, see the [Set up your coding agent guide](https://ai.google.dev/gemini-api/docs/coding-agents)25- **Migrate from `generateContent`** : If you have an existing integration, follow the [Migration guide](https://ai.google.dev/gemini-api/docs/migrate-to-interactions) to transition to the Interactions API.26- **Get started** : Follow the steps in the [Interactions API Get started27 guide](https://ai.google.dev/gemini-api/docs/get-started).2829### Feature guides3031Explore 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:3233- [Text generation](https://ai.google.dev/gemini-api/docs/text-generation)34- [Image generation](https://ai.google.dev/gemini-api/docs/image-generation)35- [Image understanding](https://ai.google.dev/gemini-api/docs/image-understanding)36- [Audio understanding](https://ai.google.dev/gemini-api/docs/audio)37- [Video understanding](https://ai.google.dev/gemini-api/docs/video-understanding)38- [Document processing](https://ai.google.dev/gemini-api/docs/document-processing)39- [Function calling](https://ai.google.dev/gemini-api/docs/function-calling)40- [Structured output](https://ai.google.dev/gemini-api/docs/structured-output)41- [Deep Research agent](https://ai.google.dev/gemini-api/docs/deep-research)42- [Flex inference](https://ai.google.dev/gemini-api/docs/flex-inference)43- [Priority inference](https://ai.google.dev/gemini-api/docs/priority-inference)4445## How the Interactions API works4647The Interactions API centers around a core resource: the [**`Interaction`**](https://ai.google.dev/api/interactions-api#Resource: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.4849When you make a call to50[`interactions.create`](https://ai.google.dev/api/interactions-api#CreateInteraction), you are51creating a new `Interaction` resource.5253### Server-side state management5455You can use the `id` of a completed interaction in a subsequent call using the56`previous_interaction_id` parameter to continue the conversation. The server57uses this ID to retrieve the conversation history, saving you from having to58resend the entire chat history.5960The `previous_interaction_id` parameter preserves only the conversation history (inputs and outputs)61using `previous_interaction_id`. The other parameters are **interaction-scoped**62and apply only to the specific interaction you are currently generating:6364- `tools`65- `system_instruction`66- `generation_config` (including `thinking_level`, `temperature`, etc.)6768This means you must re-specify these parameters in each new interaction if you69want them to apply. This server-side state management is optional; you can also70operate in stateless mode by sending the full conversation history in each71request.7273### Data storage and retention7475By default, the API stores all Interaction objects (`store=true`) in order to76simplify use of server-side state management features (with77`previous_interaction_id`), [background execution](https://ai.google.dev/gemini-api/docs/background-execution) (using `background=true`) and78observability purposes.7980- **Paid tier** : The system retains interactions for **55 days**.81- **Free tier** : The system retains interactions for **1 day**.8283If you don't want this, you can84set `store=false` in your request. This control is separate from state85management; you can opt out of storage for any interaction. However, note that86`store=false` is incompatible with [background execution](https://ai.google.dev/gemini-api/docs/background-execution) and prevents using87`previous_interaction_id` for subsequent turns.8889For Paid Tier projects, you can configure the retention window in90[AI Studio](https://aistudio.google.com/logs) to automatically mark logs for91deletion from project storage after 7, 14, 28, or 55 days. A shorter retention92may affect retrieval of past conversations.9394You can delete stored interactions at any time using the [`delete`](https://ai.google.dev/api/interactions-api#deleteInteraction) method programmatically, which95requires the interaction ID. You can also view and manage stored interactions96logs, including deletion from project storage, in97[AI Studio](https://aistudio.google.com/logs).9899After the retention period expires, your data will be100deleted automatically.101102Interactions objects are processed according to the [terms](https://ai.google.dev/gemini-api/terms).103104### View interactions in AI Studio105106The API stores Interactions API requests executed with `store=true` for107projects on the Paid Tier. You can view them directly from the108[Logs page in Google AI Studio](https://ai.google.dev/gemini-api/docs/www.aistudio.google.com/logs). See the109[Logs guide](https://ai.google.dev/gemini-api/docs/logs-datasets) for more.110111## Best practices112113- **Cache hit rate** : Implicit caching is supported in both stateful and stateless modes (see [Quickstart](https://ai.google.dev/gemini-api/docs/get-started#4_multi-turn_conversations)). Using `previous_interaction_id` (stateful) to continue conversations allows the system to more easily utilize implicit caching for the conversation history, which improves performance and reduces costs.114- **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`.115116## Supported models \& agents117118| Model Name | Type | Model ID |119|---|---|---|120| Gemini 3.8 Flash | Model | `gemini-3.8-flash` |121| Gemini 3.7 Flash | Model | `gemini-3.7-flash` |122| Gemini 3.6 Flash | Model | `gemini-3.6-flash` |123| Gemini 3.5 Flash | Model | `gemini-3.5-flash` |124| Gemini 3.1 Pro Preview | Model | `gemini-3.1-pro-preview` |125| Gemini 3.5 Flash-Lite | Model | `gemini-3.5-flash-lite` |126| Gemini 3.1 Flash-Lite | Model | `gemini-3.1-flash-lite` |127| Gemini 3 Flash Preview | Model | `gemini-3-flash-preview` |128| Gemini 2.5 Pro | Model | `gemini-2.5-pro` |129| Gemini 2.5 Flash | Model | `gemini-2.5-flash` |130| Gemini 2.5 Flash-lite | Model | `gemini-2.5-flash-lite` |131| Gemini 3 Pro Image | Model | `gemini-3-pro-image` |132| Gemini 3.1 Flash Image | Model | `gemini-3.1-flash-image` |133| Gemini 3.1 Flash TTS Preview | Model | `gemini-3.1-flash-tts-preview` |134| Gemma 4 31B IT | Model | `gemma-4-31b-it` |135| Gemma 4 26B MoE IT | Model | `gemma-4-26b-a4b-it` |136| Lyria 3.5 | Model | `lyria-3.5` |137| Lyria 3 Clip Preview | Model | `lyria-3-clip-preview` |138| Lyria 3 Pro Preview | Model | `lyria-3-pro-preview` |139| Deep Research Preview | Agent | `deep-research-preview-04-2026` |140| Deep Research Preview | Agent | `deep-research-max-preview-04-2026` |141| Antigravity Preview | Agent | `antigravity-preview-09-2026` |142143## SDKs144145You can use latest version of the Google GenAI SDKs in order to access146Interactions API.147148- On Python, this is `google-genai` package from `2.3.0` version onwards.149- On JavaScript, this is `@google/genai` package from `2.3.0` version onwards.150151You can learn more about how to install the SDKs on152[Libraries](https://ai.google.dev/gemini-api/docs/libraries) page.153154## Limitations155156- **Remote MCP**: Gemini 3 does not support remote MCP, this is coming soon.157- **Multi-turn model compatibility** : When mixing different models in a conversation (either stateful or stateless), subsequent models must support the output modalities of the previous models as input. For example, if you generate an image using `gemini-3.1-flash-image`, you cannot continue that conversation with a model that doesn't accept image inputs (such as a text-only model or a music-generation model like Lyria).158159The following features are supported by the160[`generateContent`](https://ai.google.dev/gemini-api/docs/generate-content/text-generation) API but are **not yet161available** in the Interactions API:162163- **[Batch API](https://ai.google.dev/gemini-api/docs/batch-api)**164- **[Automatic function calling (Python)](https://ai.google.dev/gemini-api/docs/function-calling?example=meeting#automatic_function_calling_python_only)**165- **[Explicit caching](https://ai.google.dev/gemini-api/docs/caching)** : Note that server-side implicit caching is available in the Interactions API via `previous_interaction_id`.166- **[Safety settings](https://ai.google.dev/gemini-api/docs/safety-settings)**: Custom safety settings are not supported in the Interactions API.167168## Feedback169170Your feedback is critical to the development of the Interactions API.171Share your thoughts, report bugs, or request features on our172[Google AI Developer Community Forum](https://discuss.ai.google.dev/c/gemini-api/4).173174## What's next175176- Try the [Interactions API quickstart notebook](https://colab.sandbox.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_interactions_api.ipynb).177- Learn more about the [Gemini Deep Research agent](https://ai.google.dev/gemini-api/docs/deep-research).