The [`chat`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt) method of the
[Data API](https://developers.google.com/analytics/devguides/reporting/data/v1/rest.md.txt) provides
programmatic
access to [Ask Advisor in Google Analytics](https://support.google.com/analytics/answer/16675569)
--- an AI-powered analytical assistant that helps you
query, analyze, and diagnose your Google Analytics data using natural language.
While Ask Advisor is available interactively within the Google Analytics
user interface, the [`chat`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt) API
allows developers, autonomous AI agents, and internal tools to interact with
Ask Advisor programmatically over HTTP.
> [!NOTE]
> **Note:** The `chat` method is available in the [v1alpha](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt) version of the Data API.
> **Important:** This product uses AI and may display inaccurate info. Your chat
> activity may be used to improve the product and your use is subject to
> Google's [Terms](https://policies.google.com/terms), [AI Use
> Policy](https://policies.google.com/terms/generative-ai/use-policy), and
> [Privacy Policy](https://policies.google.com/privacy).
## Overview
The [`chat`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt) method enables both
single-turn ad hoc data questions and multi-turn conversational sessions:
1. **Single-turn queries:** Ask immediate analytical questions (such as, "What were our top traffic channels last week?") and receive natural language answers along with structured data tables.
2. **Multi-turn conversations:** Pass a [`sessionId`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#body.request_body.FIELDS.session_id) to maintain conversation history and ask diagnostic follow-up questions (such as, "Why did organic traffic decline in that period?").
3. **Structured data responses:** In addition to text narratives, responses contain structured [`table`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#ResponseBlock.FIELDS.table) blocks with column headers and rows.
4. **Chat quota monitoring:** Inspect remaining per-day and per-hour chat token quotas by setting [`returnPropertyQuota`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#body.request_body.FIELDS.return_property_quota) to `true`.
### Authentication
Calls to the [`chat`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt) method
require OAuth 2.0 authorization with the following scope:
- [`https://www.googleapis.com/auth/analytics.chatbot.read`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#authorization-scopes)
> [!NOTE]
> **Note:** This scope is different from the scope required for standard reporting methods (such as [`runReport`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport.md.txt)).
## Before you begin
> [!TIP]
> **Tip:** To try the `chat` method interactively in Python without setting up a local environment, open the [Ask Advisor Colab
> notebook](https://developers.google.com/analytics/devguides/reporting/data/v1/notebooks/advisor-chat).
1. [Install and initialize](https://cloud.google.com/sdk/docs/install) the gcloud
CLI.
2. To generate [Application Default
Credentials](https://cloud.google.com/docs/authentication/application-default-credentials)
and give your account the necessary scopes, run the following:
```bash
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"
```
3. In the [Google Analytics UI](https://analytics.google.com), grant your user
account [access to a Google Analytics property](https://support.google.com/analytics/answer/9305788).
4.
Configure your environment variables by entering the following.
Replace `PROJECT_ID` with the ID of your project
and `PROPERTY_ID` with the ID of your Google Analytics property.
```bash
export PROJECT_ID=`PROJECT_ID`
export PROPERTY_ID=`PROPERTY_ID`
```
## Example 1: Single-turn query with quota tracking
To start a new conversation, construct a [`ChatRequest`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#request-body)
containing your [`userQuery`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#body.request_body.FIELDS.user_query).
Set [`returnPropertyQuota`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#body.request_body.FIELDS.return_property_quota)
to `true` to inspect your remaining token balance.
### Scenario: Revenue and Conversion Rate by Device
You want to compare revenue and session conversion rate across devices over the
past 30 days.
#### HTTP Request
```bash
curl -X POST \
"https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "x-goog-user-project: ${PROJECT_ID}" \
-H "Content-Type: application/json" \
-d '{
"userQuery": "Compare our revenue and conversion rate across mobile vs desktop over the last 30 days.",
"returnPropertyQuota": true
}'
```
#### HTTP Response
The response contains:
- A newly assigned [`sessionId`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#body.ChatResponse.FIELDS.session_id) that you can use for follow-up turns.
- A list of [`blocks`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#body.ChatResponse.FIELDS.blocks) containing both a natural language summary ([`text`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#ResponseBlock.FIELDS.text)) and a structured table ([`table`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#ResponseBlock.FIELDS.table)). Text blocks can contain Markdown formatting like bold text, headings, and links.
- The property's [`propertyQuota`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#body.ChatResponse.FIELDS.property_quota) details.
```json
{
"sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
"blocks": [
{
"text": "Your report on revenue and conversion rates for mobile vs. desktop over the last 30 days (August 15 - September 13, 2026) is ready.\n\nHere is a summary of your revenue and conversion rate by device category:\n"
},
{
"table": {
"headers": [
{
"header": "Device Category",
"dataType": "string"
},
{
"header": "Total Revenue",
"dataType": "string"
},
{
"header": "User Conversion Rate",
"dataType": "string"
}
],
"rows": [
{
"columns": [
{
"value": "Desktop"
},
{
"value": "$17,412.62"
},
{
"value": "99.9%"
}
]
},
{
"columns": [
{
"value": "Mobile"
},
{
"value": "$15,309.41"
},
{
"value": "99.46%"
}
]
}
}
},
{
"text": "**Revenue and Conversion Rate Trends:**\n\nRevenue from desktop devices saw a peak on August 18th, while mobile revenue peaked on August 30th. Conversion rates remained high and relatively stable for both desktop and mobile throughout the period."
},
{
"text": "This product uses AI and may display inaccurate info. Your chat activity may be used to improve the product and your use is subject to Google's [Terms](https://policies.google.com/terms), [AI Use Policy](https://policies.google.com/terms/generative-ai/use-policy), and [Privacy Policy](https://policies.google.com/privacy). [Learn more about Chat AI Privacy](https://support.google.com/helpguide/answer/14185196)."
}
],
"propertyQuota": {
"tokensPerDay": {
"consumed": 26849,
"remaining": 3723151
},
"tokensPerHour": {
"consumed": 26849,
"remaining": 473151
}
}
}
```
## Example 2: Multi-turn conversational diagnostic
To ask a follow-up question while preserving context, include the [`sessionId`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#body.request_body.FIELDS.session_id)
returned by the previous response in your request.
### Scenario: Compare with the previous period
Following up on the previous device comparison, you ask the Advisor to compare
the results with the previous period.
#### HTTP Request
```bash
curl -X POST \
"https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "x-goog-user-project: ${PROJECT_ID}" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
"userQuery": "Compare results with the same period in the previous mounth."
}'
```
#### HTTP Response
Ask Advisor uses the session memory to correlate results with the
previous period.
```json
{
"sessionId": "eb3284b2-49ce-4aed-b6d0-fdc15cb87b5f",
"blocks": [
{
"text": "The following table provides a detailed comparison of total revenue and user conversion rate by device category for the two periods.\n"
},
{
"table": {
"headers": [
{
"header": "Device Category",
"dataType": "string"
},
{
"header": "Metric",
"dataType": "string"
},
{
"header": "Jul 16 - Aug 15, 2026",
"dataType": "string"
},
{
"header": "Aug 16 - Sep 14, 2026",
"dataType": "string"
}
],
"rows": [
{
"columns": [
{
"value": "Desktop"
},
{
"value": "Total Revenue"
},
{
"value": "$17,412.62"
},
{
"value": "$19,565.46"
}
]
},
{
"columns": [
{
"value": "Desktop"
},
{
"value": "User Conversion Rate"
},
{
"value": "1.90%"
},
{
"value": "1.95%"
}
]
},
{
"columns": [
{
"value": "Mobile"
},
{
"value": "Total Revenue"
},
{
"value": "$13,997.19"
},
{
"value": "$15,309.41"
}
]
},
{
"columns": [
{
"value": "Mobile"
},
{
"value": "User Conversion Rate"
},
{
"value": "1.95%"
},
{
"value": "1.99%"
}
]
}
}
}
]
}
```
## Response Structure \& Data Blocks
The [`ChatResponse`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#response-body)
object returns structured components in the [`blocks`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#body.ChatResponse.FIELDS.blocks)
array:
| Block Type | Field | Description |
|---|---|---|
| **Narrative Text** | [`blocks[].text`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#ResponseBlock.FIELDS.text) | Human-readable explanation and high-level analytical takeaways. |
| **Structured Table** | [`blocks[].table`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#ResponseBlock.FIELDS.table) | Tabular data breakdown containing [`headers`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#DataTable.FIELDS.headers) (names and data types) and [`rows`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#DataTable.FIELDS.rows) (cell values). |
### Table Header Data Types
Columns in
[`blocks[].table.headers`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#DataTable.FIELDS.headers)
describe the semantic data type:
- `string`: Categorical text values (e.g., `"desktop"`, `"/shop/apparel"`).
- `float`: Numeric floating-point numbers.
## Chat Quota Management
Ask Advisor requests consume chat tokens based on query complexity.
The current quota state is returned in
[`propertyQuota`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#body.ChatResponse.FIELDS.property_quota)
when [`returnPropertyQuota`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#body.request_body.FIELDS.return_property_quota)
is `true`:
- [`tokensPerDay`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#PropertyChatQuota.FIELDS.tokens_per_day): Daily token limit and remaining balance.
- [`tokensPerHour`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#PropertyChatQuota.FIELDS.tokens_per_hour): Hourly sliding window rate limit and remaining balance.
## Suggested Integration Applications
The [`properties.chat`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt) method
unlocks several integration architectures across teams and tools:
### Enterprise Chat \& Collaboration Bots
Connect your team chat workspace directly to Google Analytics.
- **Threaded Sessions:** Store the [`sessionId`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#body.ChatResponse.FIELDS.session_id) against the chat thread ID to allow team members to ask follow-up questions collaboratively.
- **Rich Card Rendering:** Format [`table`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt#ResponseBlock.FIELDS.table) response blocks into interactive card widgets.
### Autonomous AI Agents \& Model Context Protocol (MCP) Tools
Equip LLM orchestrators (such as Gemini, LangChain, or Claude) with
a GA analytical tool:
- Rather than forcing an LLM to generate complex [`runReport`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport.md.txt#request-body) queries, the LLM agent can invoke the [`chat`](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat.md.txt) method with natural language intent.
- The agent receives high-factuality summaries and structured tables to synthesize into multi-channel marketing recommendations.
### Automated Executive Briefings \& Alerting
Create scheduled services that proactively investigate anomalies:
- A daily cron job queries: *"Summarize yesterday's key performance metrics and
identify any anomalous drop in conversions."*
- If an anomaly is found, the script automatically triggers a follow-up query to diagnose root causes and posts a summary digest to internal dashboards or CRM systems.
## Next steps
- Try the interactive [Ask Advisor Colab
notebook](https://developers.google.com/analytics/devguides/reporting/data/v1/notebooks/advisor-chat) to run single-turn and multi-turn queries using the Python client library.
- Review the [`properties.chat` REST API
reference](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1alpha/properties/chat).
- Learn more about [Data API quotas and limits](https://developers.google.com/analytics/devguides/reporting/data/v1/quotas.md.txt).