GA4 Auth Setup

Overview

GA4 has two production-grade auth paths. Pick before you start; mixing them mid-flight is the most common failure mode.

Recommendation: service account for any pipeline / report-runner / agent use. OAuth for a human poking around. Don't share OAuth user creds across machines — that's an audit-trail mess.

Prerequisites

• A Google Cloud project where you can create a service account and enable APIs, or a Google account with access to the target GA4 property.
• The GA4 property ID (digits only, not the G-... measurement ID).
• gcloud authenticated to the GCP project; the Python verification also needs the Google Analytics Data API client library installed.

Instructions

Examples

Path A — Service account (recommended for automation)

1. Create the SA in GCP

PROJECT=your-gcp-project          # the project that will own the SA
SA_NAME=ga4-reader
SA_EMAIL="${SA_NAME}@${PROJECT}.iam.gserviceaccount.com"

gcloud iam service-accounts create "$SA_NAME" \
  --display-name="GA4 read-only API access" \
  --project="$PROJECT"

# Generate a key (file lands locally)
gcloud iam service-accounts keys create ~/.config/gcloud/sa-ga4.json \
  --iam-account="$SA_EMAIL"

2. Grant the SA access to your GA4 property

This is the step everyone forgets. GA4 has property-level access control that lives in the Google Analytics web UI, NOT in GCP IAM. The service account email needs to be added there.

1. Open <https://analytics.google.com/>
2. Admin (bottom-left gear) → Property column → Property Access Management
3. Add user: paste $SA_EMAIL (e.g. ga4-reader@your-project.iam.gserviceaccount.com)
4. Role: Viewer (read-only — anything more is over-privilege)
5. Save

3. Enable the Data API in the SA's project

gcloud services enable analyticsdata.googleapis.com --project="$PROJECT"

4. Test the auth round-trip

GOOGLE_APPLICATION_CREDENTIALS=~/.config/gcloud/sa-ga4.json \
PROPERTY_ID=123456789 \
python3 -c …

GA4 → BigQuery Export

Overview

The Data API is good but bounded — sampled past a threshold, capped at ~150 dimensions, no cohort joins. BigQuery export gives you the raw event stream as SQL-queryable tables, free at the standard GA4 tier (up to 1M events/day), with no sampling and full event payloads.

This skill: one-time setup, then the SQL recipes for what the Data API can't do well.

Prerequisites

• A GA4 property for which you can create a BigQuery link.
• A Google Cloud project with BigQuery enabled and permission to grant project IAM roles.
• The bq and gcloud CLIs authenticated to that project; use the service account created by ga4-auth-setup for unattended queries.

Instructions

Setup — one time

1. Link your GA4 property to a GCP project

In <https://analytics.google.com/>:

1. Admin → Property column → BigQuery Links
2. Create a link → pick your GCP project
3. Data location: pick the BQ region for the export tables (US multi-region is fine for most cases; EU if you need data residency)
4. Export type:

• Daily — single events_YYYYMMDD table per day, written ~24h after midnight. Fine for most reporting.
• Streaming — events_intraday_YYYYMMDD table written ~near-real-time. Costs more, useful for hot ops dashboards.
• Most setups: enable both. Streaming for "today", daily for everything else.

1. Include advertising identifiers — uncheck unless you specifically need device-graph data (most don't)
2. Save

The first daily table lands within 24h. The first streaming table is near-immediate. After that you have a new events_YYYYMMDD every day forever, no maintenance needed.

2. Verify the export is working

PROJECT=your-gcp-project
DATASET=analytics_123456789       # auto-named after the property ID

bq ls "$PROJECT:$DATASET" 2>&1 | head -10
# Expect: events_YYYYMMDD tables + events_intraday_YYYYMMDD if streaming enabled

If you see no dataset, the link is configured but the first export hasn't fired yet — wait 24h.

3. Authorize a service account for querying

The SA from ga4-auth-setup only has Data API access. For BQ queries, grant the same SA:

SA_EMAIL=ga4-reader@your-project.iam.gserviceaccount.com
gcloud projects add-iam-policy-binding "$PROJECT" \
  --member="serviceAccount:$SA_EMAIL" \
  --role="roles/bigquery.dataViewer"
gcloud projects add-iam-policy-binding "$PROJECT" \
  --member="serviceAccount:$SA_EMAIL" \
  --role="roles/bigquery.jobUse…

GA4 Common Reports

Overview

Recipes for the reports that get asked for ~95% of the time. Each one is a complete runReport you can paste, change PROPERTY_ID, and run. Prerequisite: ga4-auth-setup done.

Prerequisites

• A GA4 Data API credential configured by ga4-auth-setup and granted Viewer access to the target property.
• Python with google-analytics-data installed and GA4_PROPERTY_ID set to the numeric property ID.
• A clear reporting window; use completed days for stable comparisons.

Instructions

The setup block (same for every recipe):

import os
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    RunReportRequest, DateRange, Metric, Dimension,
    FilterExpression, Filter, OrderBy,
)

PROPERTY = f"properties/{os.environ['GA4_PROPERTY_ID']}"
client = BetaAnalyticsDataClient()

Examples

1. Daily Active Users (DAU) — 30-day rolling

req = RunReportRequest(
    property=PROPERTY,
    date_ranges=[DateRange(start_date="30daysAgo", end_date="yesterday")],
    metrics=[Metric(name="activeUsers")],
    dimensions=[Dimension(name="date")],
    order_bys=[OrderBy(dimension=OrderBy.DimensionOrderBy(dimension_name="date"))],
)
resp = client.run_report(req)
for r in resp.rows:
    print(f"{r.dimension_values[0].value} {r.metric_values[0].value}")

Why yesterday, not today: today's number is incomplete and will keep climbing through the day. For a clean rolling DAU, end the window at yesterday.

2. MAU / WAU — rolling unique users

GA4 doesn't expose MAU as a single metric — you compute it from the same activeUsers rolled up over a wider date range. The trick: a single-row report with no date dimension returns the unique count over the entire window (de-duplicated across days).

# MAU (last 30 days)
mau = client.run_report(RunReportRequest(
    property=PROPERTY,
    date_ranges=[DateRange(start_date="29daysAgo", end_date="yesterday")],
    metrics=[Metric(name="activeUsers")],
))
mau_count = int(mau.rows[0].metric_values[0].value) if mau.rows else 0

# WAU (last 7 days)
wau = client.run_report(RunReportRequest(
    property=PROPERTY,
    date_ranges=[DateRange(start_date="6daysAgo", end_date="yesterday")],
    metrics=[Metric(name="activeUsers")],
))
wau_count = int(wau.rows[0].metric_values[0].value) if wau.rows else 0

print(f"MAU: {mau_count:,}   WAU: {wau_count:,}   Ratio (engagement): {wau_count/mau_count:.2%}")

Stickiness rule-of-thu…

GA4 Data API v1 — runReport

Overview

The Data API v1 is the canonical read path for GA4. One endpoint (runReport) covers most use cases. Two paths matter for picking the right query: dimensions describe rows (date, page, source), metrics describe values (sessions, users, events). Not every combination is valid — see "Compatibility" below.

Prerequisite: auth working (see ga4-auth-setup).

Prerequisites

• An authenticated GA4 Data API client with access to the target property; follow ga4-auth-setup first.
• Python and the google-analytics-data package.
• A numeric GA4 property ID and a bounded date range appropriate to the metric's freshness.

Instructions

Examples

The minimum viable query

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    RunReportRequest, DateRange, Metric, Dimension,
)

client = BetaAnalyticsDataClient()

req = RunReportRequest(
    property="properties/123456789",     # YOUR property ID (digits only)
    date_ranges=[
        DateRange(start_date="30daysAgo", end_date="today"),
    ],
    metrics=[Metric(name="activeUsers")],
    dimensions=[Dimension(name="date")],
)
resp = client.run_report(req)

for row in resp.rows:
    date = row.dimension_values[0].value     # YYYYMMDD string
    users = row.metric_values[0].value       # numeric string
    print(f"{date}: {users}")

That's the full skeleton. Everything below extends this shape.

The 12 metrics worth knowing

GA4 Realtime API

Overview

The Realtime API is GA4's "what's happening right now" endpoint. Different from runReport:

Don't try to use runReport for now-data — its freshest data point is yesterday. Use runRealtimeReport.

Prerequisites

• A GA4 Data API credential with access to the target property, configured through ga4-auth-setup.
• Python with google-analytics-data installed.
• A numeric property ID; realtime data is inherently a rolling, roughly 30-minute view and is not a replacement for historical reporting.

Instructions

Examples

Minimum viable call

from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
    RunRealtimeReportRequest, Metric, Dimension,
)

client = BetaAnalyticsDataClient()
resp = client.run_realtime_report(RunRealtimeReportRequest(
    property="properties/123456789",
    metrics=[Metric(name="activeUsers")],
))

# Single-row response when there are no dimensions
total = int(resp.rows[0].metric_values[0].value) if resp.rows else 0
print(f"Active users right now: {total}")

No date_ranges block — the implicit window is the last 30 min. Adding one will error.

Realtime metrics (the full list)

Custom-event aggregates (e.g. purchase_revenue) are NOT in the Realtime API. If you need realtime revenue, derive it from eventCount filtered to eventName=="purchase" plus your avera…