Frequently asked questions about the Conversational Analytics API

Can the Conversational Analytics API alter or delete my data?

The Conversational Analytics API is designed with safeguards to prevent altering or deleting your data.

Here's how data safety is handled for different data sources:

BigQuery: The API blocks Data Definition Language (DDL) and Data Manipulation Language (DML) statements. Specifically, the system performs a test run on generated SQL and only permits SELECT type queries.
Looker: The API interacts with Looker by using methods like run_inline_query , which are restricted to read operations such as selections, filters, and limits. These methods don't support DDL or DML operations and don't include delete or drop operations.
Looker Studio (for CSVs and Google Sheets): Looker Studio uses a structured format to define and fetch data for visualizations and reports. Any queries that are executed with this method are read-only and don't support data mutations.

The Conversational Analytics API is designed to be read-only across these data sources.

How do I handle authentication and permission errors?

Here are some common authentication and permission errors you might encounter when using the Conversational Analytics API:

Error: PERMISSION_DENIED or 403 Write access to project ... was denied
- Likely Cause: This message often indicates issues with Google Cloud IAM roles. The user or service account that is attempting to use the API lacks the necessary permissions on the Google Cloud project.
- Troubleshooting:
  - The Google Cloud project owner must ensure that the user or service account has the correct IAM roles assigned in the Google Cloud project. Roles like Project Editor might be needed for certain operations, such as enabling the API or testing its functions.
  - If you encounter a 403 error like Write access to project 'us-gcp-project-name' was denied when switching regions, verify your project's IAM configuration.
Error: 500 Internal Server Error when a Looker user with a Userrole tries to chat with a data agent.
- Likely Cause: The Looker user might not have sufficient permissions.
- Troubleshooting: Make sure that users are granted the appropriate roles in IAM and in Looker to chat with a data agent. See the answer to What are the Looker requirements for using the Conversational Analytics API? in this FAQ for more information.

What are the Looker requirements for using the Conversational Analytics API?

To use the Conversational Analytics API, you need appropriate permissions both in Google Cloud IAM and within Looker, depending on the data source and the actions that you want to perform:

Google Cloud IAM roles:
- You need sufficient IAM roles on your Google Cloud project to interact with the geminidataanalytics.googleapis.com API. Misconfigured IAM roles often lead to PERMISSION_DENIED errors.
- The specific roles required can depend on the actions, but general roles like Project Editormight be necessary for certain operations.
Looker permissions and roles:
- Model level permissions: To use Conversational Analytics and the Conversational Analytics API, a Looker user must be assigned a role that contains gemini_in_looker permission for the models that they interact with.

To learn more about the permissions and roles that are required to use the Conversational Analytics API, see the Grant Conversational Analytics API IAM roles and permissions documentation page for more information.

Additionally, your Looker instance must meet specific requirements:

To use the Conversational Analytics API with Looker Studio Pro, your Pro subscription must be outside of a VPC-SC perimeter.

How do I migrate from the Data QnA API to the Conversational Analytics API?

If you used the older, experimental version of the Data QnA API ( dataqna.googleapis.com ), see the migration guide for how to migrate to the new, official endpoint for the Conversational Analytics API ( geminidataanalytics.googleapis.com ).

What is the difference between a data agent's name and its ID?

The data agent's ID, which is defined as the value for data_agent_id , is the unique identifier for the data agent. The data agent's name, data_agent.name , is derived automatically from the data_agent_id as a fully qualified name (FQN), taking the form projects/<project>/locations/<location>/dataAgents/<data_agent_id> .

When creating a data agent, any value that you may have entered for data_agent.name is ignored. When performing get , update , or delete operations, the full data_agent.name is treated as the unique identifier of the data agent.

When using the Conversational Analytics API to create data agents, the following scenarios apply:

If you don't define data_agent_id , a unique ID is generated automatically.
If you define data_agent_id as, for example, TestID , any value that you may have entered for data_agent.name is overwritten with projects/<project>/locations/<location>/dataAgents/TestID .
If you define data_agent_id with a FQN, you receive a "malformed name" error.

What are the Conversational Analytics API data agent's memory capabilities?

Within a single session: The Conversational Analytics API supports multi-turn conversations, meaning it can reference earlier parts of the current conversation.
Across multiple sessions: The Conversational Analytics API includes features for managed conversation history, allowing users to chat over multiple sessions. It also supports stateful agents with Google-managed multi-turn conversations.
Long-term memory: Conversational Analytics API data agents don't support explicit long-term memory capabilities.

Will a Conversational Analytics API data agent give me the same answer every time I ask the same question?

Natural language responsesfrom the Conversational Analytics API data agent aren't deterministic, so the natural language answer provided by the agent may vary even for an identically worded question.
Data query responses: However, for a specific data-seeking question, the underlying generated query (SQL or Looker query) is expected to be deterministic. The data that's retrieved should be the same, assuming that the underlying data hasn't changed.

How can I improve the accuracy of the responses from a Conversational Analytics API data agent?

One way to improve the accuracy of data agent responses is to provide the data agent with robust contextual information. You can add context in the following ways:

In Looker's semantic layer, you can provide context within the LookML definitions. For more information and examples, see the Guide agent behavior with authored context in Looker documentation page.
When you're creating a data agent, you can provide system instructions, which are user-defined guidance that can shape the behavior of a data agent. This guidance includes business-specific logic, response formatting, or data presentation. You can also provide "golden queries," which are sample natural language questions that are paired with their correct SQL or Looker queries. For more information about system instructions, see the Guide agent behavior with authored context documentation page.

Can I integrate the Conversational Analytics API with third-party applications?

Integrating the Conversational Analytics API with third-party applications allows users to interact with their data directly within the tools that they use daily.

Any third-party application that interacts with the geminidataanalytics.googleapis.com API endpoints must be able to send user messages from the application to the agent and display the responses.

To build an integration, see the Conversational Analytics Quickstarts repository for examples or libraries. You can also visit the Google Developer Forums to search for examples from other users.

How much does the Conversational Analytics API cost?

The Conversational Analytics API is in a Preview phase, and Google does not charge for products in Preview. We will provide advanced notice of any pricing changes in the future.

What data sources does the Conversational Analytics API support?

The Conversational Analytics API supports the following data sources:

BigQuery
Looker Explores
Looker Studio

You can also connect to sources like SAP and Salesforce through BigQuery, and to CSVs and Google Sheets through Looker Studio.

What are the known limitations of the Conversational Analytics API?

To learn more about the known limitations of the Conversational Analytics API, see the Conversational Analytics API known limitations documentation page.

What quotas do I need to be aware of for Google Cloud projects?

There are no restrictions on Google Cloud project selection or location. You can create data agents to query supported data sources that belong to any project or region.

Does the Conversational Analytics API support data regionalization?

Because the Conversational Analytics API does notyet support data residency (DRZ) or service control perimeters (VPC-SC), you cannot yet host agents in specific geographic regions. Data regionalization is not supported.

Does the Conversational Analytics API support languages other than English?

The only officially supported language for the Conversational Analytics API is English. Although the underlying Gemini models support many languages, and some users have reported anecdotal success with non-English queries, the Conversational Analytics API doesn't officially support languages other than English.