Conversational Analytics API: Build data agents and chat with your data

Developers can use the Conversational Analytics API, which is accessed through geminidataanalytics.googleapis.com , to build an artificial intelligence (AI)-powered chat interface, or data agent , that uses natural language to answer questions about structured data in BigQuery, Looker, and Looker Studio. With the Conversational Analytics API, you provide your data agent with business information and data ( context ), as well as access to tools such as SQL, Python, and visualization libraries. These agent responses are presented to the user and can be logged by the client application, creating a seamless and auditable data chat experience.

Learn how and when Gemini for Google Cloud uses your data .

Get started with the Conversational Analytics API

To start using the Conversational Analytics API, you can first review the architecture and key concepts documentation to understand how agents process requests, the workflows for agent creators and users, conversation modes, and Identity and Access Management (IAM) roles. Then, to start building data agents, you can choose between a guided experience with quickstarts , codelabs , notebooks , the Agent Development Kit (ADK) and MCP Toolbox , or a self-driven approach by following the steps in Setup and prerequisites .

Quickstarts

Use the Streamlit Quickstart app to integrate with the Conversational Analytics API in a local test environment.

Codelabs

Follow a step-by-step tutorial to learn how to use the Python SDK with BigQuery data with the Conversational Analytics API Codelab .

Notebooks

Use the following Conversational Analytics API Colaboratory notebooks for guided experiences to help you get started with the Conversational Analytics API:

HTTP Colaboratory notebook : Provides an interactive, step-by-step guide to setting up your environment, building a data agent, and making API calls by using HTTP requests.
Python SDK Colaboratory notebook : Provides an interactive, step-by-step guide to setting up your environment, building a data agent, and making API calls by using the Python SDK.

Agent Development Kit (ADK) and MCP Toolbox

Learn how to use the ask_data_insights function in the Agent Development Kit (ADK) to answer questions about your data in natural language.

Review the Conversational Analytics demos and tools that showcase the Conversational Analytics API capabilities and provide practical integration patterns.

Setup and prerequisites

Before you use the API or the examples, complete the following steps:

Enable the Conversational Analytics API : Describes prerequisites to enable the Conversational Analytics API.
Conversational Analytics API access control with IAM : Describes how to use Identity and Access Management to share and manage access to data agents.
Authenticate and connect to a data source with the Conversational Analytics API : Provides instructions for authenticating to the API and configuring connections to your BigQuery, Looker, and Looker Studio data.

Build and interact with a data agent

After completing the previous steps, use the Conversational Analytics API to build and interact with a data agent by following these steps:

Build a data agent using HTTP : Provides a complete example of building and interacting with a data agent by using direct HTTP requests with Python.
Build a data agent using the Python SDK : Provides a complete example of building and interacting with a data agent by using the Python SDK.
Guide agent behavior with authored context : Learn how to provide authored context to guide agent behavior and improve response accuracy. You can also view examples of authored context with BigQuery data sources and with Looker data sources .
Render a Conversational Analytics API agent response as a visualization : Provides an example of processing chart specifications from API responses and rendering them as visualizations by using the Python SDK and the Vega-Altair library.

Best practices

Review the following guides to learn about best practices for using the Conversational Analytics API:

Manage BigQuery costs for your agents : Learn how to monitor and manage BigQuery costs for your Conversational Analytics API agents by setting project-level, user-level, and query-level spending limits.
Ask effective questions : Learn how to craft effective questions for your agents to get the most out of the Conversational Analytics API.
Troubleshoot Conversational Analytics API errors : Troubleshoot common Conversation Analytics API errors.
Known limitations : Provides detailed information about known limitations of the Conversational Analytics API, including limitations of queries, data, visualizations, and questions.

Key API operations

The API provides the following core endpoints for managing data agents and conversations:

Operation

HTTP method

Endpoint

Description

Create an agent

POST

/v1beta/projects/*/locations/*/dataAgents

Creates a new data agent.

Get an agent

GET

/v1beta/projects/*/locations/*/dataAgents/*

Retrieves the details of a specific data agent.

Get Identity and Access Management policy

POST

/v1beta/projects/*/locations/*/dataAgents/*:getIamPolicy

Gets the Identity and Access Management permissions that are assigned to each user for a specific data agent. Users with a Data Agent Owner role can call this endpoint to view the data agent's Identity and Access Management policy before using the setIAMpolicy endpoint to share a data agent with other users.

Set Identity and Access Management policy

POST

/v1beta/projects/*/locations/*/dataAgents/*:setIamPolicy

Sets the Identity and Access Management policy for a specific data agent. Users with a Data Agent Owner role should call this endpoint to share a data agent with other users, which effectively updates those users' Identity and Access Management permissions.

Update an agent

PATCH

/v1beta/projects/*/locations/*/dataAgents/*

Modifies an existing data agent.

List agents

GET

/v1beta/projects/*/locations/*/dataAgents

Lists available data agents in a project.

List accessible agents

GET

/v1beta/projects/*/locations/*/dataAgents:listaccessible

Lists accessible data agents in a project. A data agent is considered accessible if the user that invokes this API has the get permission on the agent. You can use the creator_filter field to manage which agents this method returns:

NONE (default): Returns all data agents that are accessible to the user, regardless of who created the agents.
CREATOR_ONLY : Returns only the data agents that are accessible to the user and that were created by that user.
NOT_CREATOR_ONLY : Returns only the data agents that are accessible to the user and that were created by others.

Delete an agent

DELETE

/v1beta/projects/*/locations/*/dataAgents/*

Removes a data agent.

Create a conversation

POST

/v1beta/projects/*/locations/*/conversations

Starts a new, persistent conversation.

Chat by using a conversation reference

POST

/v1beta/projects/*/locations/*:chat

Continues a stateful conversation by sending a chat message that references an existing conversation and its associated agent context. For multi-turn conversations, Google Cloud stores and manages the conversation history.

Chat by using a data agent reference

POST

/v1beta/projects/*/locations/*:chat

Sends a stateless chat message that references a saved data agent for context. For multi-turn conversations, your application must manage and provide the conversation history with each request.

Chat by using inline context

POST

/v1beta/projects/*/locations/*:chat

Sends a stateless chat message by providing all context directly in the request, without using a saved data agent. For multi-turn conversations, your application must manage and provide the conversation history with each request.

Get a conversation

GET

/v1beta/projects/*/locations/*/conversations/*

Retrieves the details of a specific conversation.

List conversations

GET

/v1beta/projects/*/locations/*/conversations

Lists the conversations in a specific project.

List messages in a conversation

GET

/v1beta/projects/*/locations/*/conversations/*/messages

Lists messages within a specific conversation.

Delete a conversation

DELETE

/v1beta/projects/*/locations/*/conversations/*

Deletes a specific conversation. The Topic Admin Identity and Access Management role or at least the cloudaicompanion.topics.delete Identity and Access Management permission is required to call this endpoint.

Send feedback

Use the following links to file a bug or request a feature.

Additional resources

The Conversational Analytics API REST reference provides detailed descriptions of methods, endpoints, and type definitions for request and response structures.