Skip to main content

​
Overview

The Google Analytics 4 integration gives your agents live access to your GA4 data via the official GA4 Data API. Agents can pull traffic, engagement, conversion, and revenue metrics across any GA4 property the connected Google account can read — sliced by the dimensions you care about and comparable period-over-period. Setup is one-click Google OAuth at the org level: an admin connects once, and every agent in the organization can query GA4. The connect flow shares the same Aster-side OAuth client as Google Search Console — connecting one does not connect the other, but the plumbing is identical.

​
Prerequisites

  • A Google account that has access to at least one Google Analytics 4 property
  • An Aster admin to connect the integration (the connection is shared org-wide)

​
Setup Guide

1

Connect Google Analytics in Aster Agents

Navigate to Control Hub > Integrations, locate the Google Analytics card, and click Connect. You’ll be redirected to Google to sign in.
2

Sign in with a Google account that has property access

Choose the Google account that can read your GA4 properties and approve the requested read-only access. Aster’s OAuth app is in Google’s production audience, so the refresh token is durable — the connection persists indefinitely unless someone revokes access. There is no per-customer GCP setup: no project creation, no API enablement, no service-account email to add to property permissions.
3

Add Tools to Your Agent

Edit your agent and enable List GA4 Properties and Run GA4 Report. The agent looks up the right property ID at runtime, then runs reports against it.

​
Available Tools

  • List GA4 Properties (ga4_list_properties) — Discover every GA4 account and property the connected Google account can read, via the Admin API’s accountSummaries endpoint. Agents grab the right property ID at runtime instead of hard-coding it.
  • Run GA4 Report (ga4_run_report) — A full-fidelity wrapper around the Data API’s runReport. Supply a property ID plus the metrics you want and (optionally) dimensions, dimension/metric filters, ordering, pagination, and one or two date ranges. Use two date ranges (each with a name) for period-over-period comparison. Returns flattened rows where each row is {dim1: value, …, metric1: number, …} — far easier to reason about than the API’s raw dimensionValues / metricValues arrays. Common dimensions and metrics are listed in the tool description so agents pick valid names on the first try.
When a report returns more rows than fit comfortably inline, the full row set spills to a CSV attachment (columns = your dimensions then your metrics) and the inline payload is truncated to a token budget. The CSV is auto-mounted into the execute_python sandbox at /home/user/, so an agent can run the comparison math in pandas without overflowing its context.

​
Example Prompts

Once connected, agents can answer questions like:
  • “What were our top 10 landing pages last month by sessions?”
  • “Compare conversion rate by source between this quarter and last.”
  • “Which channels drove the most revenue over the last 28 days?”
  • “Break down engaged sessions by device category for the last 7 days.”
The connection is shared by every agent in your organization and reads only the GA4 properties the connected Google account can access. Use agent-level tool permissions to control which agents can query Analytics.

​
Security Considerations

  • Read-only — the integration only requests read access to GA4 data; agents cannot modify your property or its configuration.
  • Org-level connection — one admin connects once for the whole organization. Tokens never leave the server and are redacted in API responses; access tokens auto-refresh behind the scenes.
  • Grant the GA4 tools only to agents that need them.
  • Revoke any time — disconnect from the connection modal under Control Hub > Integrations, or revoke Aster’s access from your Google Account permissions.

​
Troubleshooting

  • The connected Google account doesn’t have access to any GA4 property. Grant that account at least Viewer access on a property in GA4 (Admin → Property Access Management), or reconnect with a Google account that already has access.
  • The connection may have been revoked on the Google side. Reconnect from the Google Analytics card under Control Hub > Integrations.
  • GA4 metric and dimension names are case-sensitive API names (e.g. sessions, activeUsers, screenPageViews, sessionDefaultChannelGroup). The tool description lists the common ones — match them exactly.
  • GA4 processes data with a delay and may sample or revise very recent days. Widen the date range or wait for the data to finalize.
  • Google Search Console — live clicks, impressions, CTR, and ranking data. Shares the same one-click Google OAuth plumbing.
  • Execute Python — analyze large GA4 reports (the CSV spillover attachment) with pandas: period-over-period comparisons, trend math, segmentation.