Using the Analytics Advisor to query and analyze your data

The chat method of the Data API provides programmatic access to Analytics Advisor — an AI-powered analytical assistant that helps you query, analyze, and diagnose your Google Analytics data using natural language.

While Analytics Advisor is available interactively within the Google Analytics user interface, the chat API allows developers, autonomous AI agents, and internal tools to interact with Analytics Advisor programmatically over HTTP.

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, AI Use Policy, and Privacy Policy.

Overview

The chat 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 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 blocks with column headers and rows.
  4. Chat quota monitoring: Inspect remaining per-day and per-hour chat token quotas by setting returnPropertyQuota to true.

Authentication

Calls to the chat method require OAuth 2.0 authorization with the following scope:

Before you begin

  1. Install and initialize the gcloud CLI.

  2. To generate Application Default Credentials and give your account the necessary scopes, run the following:

    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, grant your user account access to a Google Analytics property.

  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. 

      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 containing your userQuery. Set returnPropertyQuota 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

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 that you can use for follow-up turns.
  • A list of blocks containing both a natural language summary (text) and a structured table (table). Text blocks can contain Markdown formatting like bold text, headings, and links.
  • The property's propertyQuota details.
{
  "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 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

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

Analytics Advisor uses the session memory to correlate results with the previous period.

{
  "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 object returns structured components in the blocks array:

Block Type Field Description
Narrative Text blocks[].text Human-readable explanation and high-level analytical takeaways.
Structured Table blocks[].table Tabular data breakdown containing headers (names and data types) and rows (cell values).

Table Header Data Types

Columns in blocks[].table.headers describe the semantic data type:

  • string: Categorical text values (e.g., "desktop", "/shop/apparel").
  • float: Numeric floating-point numbers.

Chat Quota Management

Analytics Advisor requests consume chat tokens based on query complexity. The current quota state is returned in propertyQuota when returnPropertyQuota is true:

  • tokensPerDay: Daily token limit and remaining balance.
  • tokensPerHour: Hourly sliding window rate limit and remaining balance.

Suggested Integration Applications

The properties.chat 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 against the chat thread ID to allow team members to ask follow-up questions collaboratively.
  • Rich Card Rendering: Format 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 queries, the LLM agent can invoke the chat 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.