Ga4 analyst

GA4 Analyst

Retrieve Google Analytics 4 data and turn it into a defensible analysis. GA4 is an event-based model (no UA sessions/pageviews semantics), reached two ways: the GA4 Data API (aggregated reports, channel groups, attribution - fast, no SQL) and the BigQuery export (raw event rows - unsampled, unlimited cardinality, custom sessionization, joins). This skill covers the data model, both retrieval paths, the full dimension/metric catalog, and an analysis playbook.

Target LLM: Claude (Claude Code / claude.ai).

When to use

• Pull a GA4 report (top pages, channels, conversions, revenue, retention…) for a property
• Write a GA4 Data API request or a BigQuery SQL query against the events export
• Decide which dimensions/metrics answer a question, and whether they're compatible
• Analyze acquisition / engagement / monetization / retention / funnels / attribution / segments
• Explain or sanity-check GA4 numbers (sampling, thresholding, (not set), users-inflation, GA4-vs-UA gaps)

Not for: instrumenting/collecting events on a site (tagging/gtag/GTM/Measurement Protocol is the collection side - see references/data-model.md for the model, but implementation is out of scope); non-GA analytics.

Prerequisites (read first if not yet set up)

Retrieval needs credentials. Before any query, confirm the property ID and access - see references/auth-setup.md (numeric properties/<ID>, Data API enabled, a service account granted Viewer/Analyst on the GA4 property, GOOGLE_APPLICATION_CREDENTIALS set; BigQuery export linked + roles/bigquery.dataViewer+jobUser for the SQL path). Never hardcode or commit credentials.

Choose the retrieval path

digraph ga4_path {
  "Need raw events, custom sessions, joins, unsampled, or >1 high-cardinality dim?" [shape=diamond];
  "BigQuery export (SQL)" [shape=box];
  "Standard aggregates, channels, attribution, quick?" [shape=diamond];
  "GA4 Data API (runReport)" [shape=box];
  "Need raw events, custom sessions, joins, unsampled, or >1 high-cardinality dim?" -> "BigQuery export (SQL)" [label="yes"];
  "Need raw events, custom sessions, joins, unsampled, or >1 high-cardinality dim?" -> "Standard aggregates, channels, attribution, quick?" [label="no"];
  "Standard aggregates, channels, attribution, quick?" -> "GA4 Data API (runReport)" [label="yes"];
}

Data API = the default for most reporting (channel groups & attribution models are computed for you; subject to quotas, sampling on huge explorations, and data thresholds). BigQuery = when you need raw fidelity, custom logic, or joins (you sessionize and compute channels yourself). Full trade-off table in references/bigquery-export.md §1.

Workflow

1. Clarify the business question, the metric of interest, the date range, and the scope (user / session / event / item).
2. Pick the path (above) and confirm auth.
3. Choose dimensions & metrics from references/dimensions-metrics.md; verify they combine (scope-mixing pitfalls; checkCompatibility).
4. Build & run the query - Data API via scripts/ga4_report.py, BigQuery via scripts/bq_ga4_query.py (or hand-built per references/data-api.md / bigquery-export.md).
5. Validate the result: sampling/thresholding flags, (not set)/(other), freshness (24–48h), consent gaps, GA4-vs-UA expectations (references/data-model.md).
6. Analyze: compute KPIs, compare vs baseline/period/segment, find drivers (references/analysis-playbook.md).
7. Report insight-first: headline → numbers with context → driver → recommendation → caveats.

Load on demand

Trigger	Load
GA4 concepts, scopes, identity, sessions/engagement, channels, attribution, GA4-vs-UA, data-quality caveats	references/data-model.md
Building a Data API request (methods, request body, filter syntax, quotas, realtime/pivot/funnel/cohort)	references/data-api.md
Exact dimension/metric API names + custom defs + compatibility	references/dimensions-metrics.md
Raw event retrieval, schema, UNNEST patterns, SQL recipes, cost control	references/bigquery-export.md
How to analyze (report families, KPI formulas, funnels, attribution, segments, anomalies, pitfalls, report template)	references/analysis-playbook.md
Setting up credentials / property ID / API & BigQuery access	references/auth-setup.md

Run the tools

# GA4 Data API - top landing pages by sessions, last 28 days, with engagement rate (CSV)
python3 scripts/ga4_report.py --property 123456789 \
  --dimensions landingPage --metrics sessions,engagementRate \
  --start 28daysAgo --end yesterday --order-by sessions:desc --limit 25

# BigQuery export - dry-run a query first to see bytes scanned, then run
python3 scripts/bq_ga4_query.py --query-file my_query.sql --dry-run
python3 scripts/bq_ga4_query.py --query-file my_query.sql --format csv --out result.csv

Both authenticate via Application Default Credentials and call only Google's official APIs with your own credentials. Install: pip install google-analytics-data google-cloud-bigquery. See scripts/README.md.

Quick reference

• Scopes: prefix tells you the scope - firstUser* (acquisition), session* (session-scoped), unprefixed/event-level. Don't mix item-scoped dimensions with session metrics.
• High-value metrics: activeUsers, sessions, engagedSessions, engagementRate, averageSessionDuration, screenPageViews, eventCount, keyEvents (= renamed "conversions"), totalRevenue, purchaseRevenue, ecommercePurchases, averageRevenuePerUser.
• High-value dimensions: date, sessionDefaultChannelGroup, sessionSourceMedium, firstUserDefaultChannelGroup, landingPage, pagePath, eventName, country, deviceCategory, newVsReturning.
• Custom: customEvent:<name>, customUser:<name>, customItem:<name> - discover available ones via getMetadata.
• KPIs you compute yourself: bounce rate = 1 − engagementRate; AOV = revenue / transactions; ARPU = revenue / activeUsers. For conversion rate, prefer the returned metric sessionKeyEventRate (or per-event sessionKeyEventRate:<event>) = converting sessions / total sessions - not raw keyEvents / sessions (which counts events, not deduplicated sessions).
• BigQuery has no channel-group field: defaultChannelGroup doesn't exist in the raw export - reconstruct Google's rules (references/data-model.md §6) or use the Data API for channels/attribution.

Common pitfalls (full table in analysis-playbook.md)

• Prefer sessions over users for trends (users inflate across identity spaces).
• engagementRate / bounceRate are session-scoped - pair with landingPage, not arbitrary page dims.
• Sampling (large explorations) and thresholding (demographics/signals) silently alter results - check response metadata.
• (not set) = missing dimension value; (other) = high-cardinality overflow row.
• Don't compare GA4 to Universal Analytics 1:1 - sessions, bounce, and "pageviews" are redefined.
• Data is not final for 24–48h; BigQuery events_intraday_* is incomplete.
• Consent-rejecting users are largely invisible (modeled, not raw).

Reference files

• references/data-model.md - event model, scopes, identity, sessions/engagement, key events, channels, attribution, GA4-vs-UA, data quality.
• references/data-api.md - Data API v1 query construction (methods, request body, filters, pagination, quotas, auth).
• references/dimensions-metrics.md - the dimension & metric catalog (API names, custom defs, realtime, compatibility).
• references/bigquery-export.md - BigQuery export schema, UNNEST patterns, 12 SQL recipes, cost control.
• references/analysis-playbook.md - analysis workflow, report families, KPI formulas, funnels/attribution/segments, pitfalls, report template.
• references/auth-setup.md - property ID, service-account/OAuth auth, BigQuery linking, secrets hygiene, prerequisites checklist.
• scripts/ - ga4_report.py (Data API), bq_ga4_query.py (BigQuery), requirements.txt, README.md.