Google Analytics 4 Query Helper
Avoid common GA4 API pitfalls that return misleading data instead of errors.
Installation
- Make sure Claude is on your device and in your terminal.
Skills load from
~/.claude/skills/when Claude Code starts up — so you need it on your machine first. If you don't have it yet, install it once with the command below, then runclaudein any terminal to verify.One-time setupnpm i -g @anthropic-ai/claude-codeAlready have it? Skip ahead.
- Paste into Claude Code or into your terminal.
This copies the whole skill folder into
~/.claude/skills/google-analytics-superdesigndev/— the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Safe default: works for every skill.Faster alternative (instruction-only skills)
Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates — they won't be downloaded and the skill will fail when it tries to load them.
Quick install (SKILL.md only)Sign up to copy - Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from
~/.claude/skills/). New skills are picked up on startup. - Just ask Claude.
Skills auto-activate when your request matches the skill's description — no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the “What this skill does” section above.
Prefer to read the source first? Open on GitHub.
When Claude uses it
Traps to avoid when querying Google Analytics 4 through treg — cases where the GA4 Data API returns a confident wrong answer instead of an error. Use whenever answering questions about site traffic, visitors, pageviews, channels, conversions, or revenue from GA4.
What this skill does
GA4 via treg — what will silently mislead you
You already know the GA4 Data API. This file is only the things that return a plausible wrong answer with no error. Everything here was verified live on 2026-07-22, and each trap was confirmed by watching three independent agents walk into it.
Property id: treg connections ls → the google-analytics row's resource_ref.
1. endDate:"today" silently includes a partial day
3 of 3 agents did this. It inflates every number and you will not notice.
28daysAgo → today /top-page = 45,120 ← includes a partial day
28daysAgo → yesterday /top-page = 44,300
Use yesterday unless the user explicitly asks about today. If you must use today, say the
last day is partial.
2. Zero does not mean zero — check whether it's even tracked
3 of 3 agents reported "$0 revenue and 0 conversions" for a business with real revenue. Two
rated it high confidence; one argued the zero was trustworthy because eventCount was large.
keyEvents, conversions, and totalRevenue all return 0 when nothing is instrumented,
which is indistinguishable from genuinely zero. Before reporting any zero:
# does this property have ANY key events configured?
--data '{"dateRanges":[...],"metrics":[{"name":"keyEvents"}]}'
Don't request keyEvents and conversions in the same call — they're aliases and GA4 rejects
it with 400 Found duplicate metrics: conversions. Pick one.
If keyEvents is 0 across a long window on a site with traffic, the correct answer is
"conversions are not instrumented in GA4; this question can't be answered from this source" —
never "revenue is $0". Revenue almost certainly lives in Stripe/PostHog instead.
3. A zero-row response has NO rows key at all
Not rows: [] — the key is absent, and so is rowCount. The shape varies by query:
| Query | Top-level keys returned |
|---|---|
| grouped by a dimension | ['dimensionHeaders','metricHeaders','metadata','kind'] |
metrics only (e.g. keyEvents) | ['metadata','kind'] — headers gone too |
A naive d['rows'] raises KeyError, which reads as a malformed request. All three unskilled
agents were confused by this. Use d.get('rows', []), treat empty as "no data", then apply
trap #2.
3b. Don't list dateRange as a dimension
Comparing two periods is a standard ask, and the obvious move errors:
400: "Field dateRange is not a dimension. This field can be used in a Pivot or
OrderBy like a dimension, but does not need to be listed in the Dimensions."
Pass 2+ entries in dateRanges and the API auto-appends the range as an extra dimension
value. Give the ranges names to label them in the output.
4. Dimension sums do NOT equal totals — they overcount
Measured against a dimensionless true total (illustrative, ratios are the point):
| Grouped by | Sum | vs true total |
|---|---|---|
sessionDefaultChannelGroup | ~104% | |
country | ~104% | |
pagePath | ~189% |
Sessions span multiple pages, so per-page sums double-count badly. Never sum a dimension to report a total — run a separate dimensionless query.
5. limit defaults to 10,000 and truncates silently
An unlimited pagePath query returned exactly 10,000 rows with "rowCount": 42613 — 32,613 rows
dropped, no warning. rowCount is the truth; len(rows) is not. Compare them before saying
"all" or "every".
6. The Admin API is a different host and is unreachable via /call/
The tool is bound to analyticsdata.googleapis.com. Anything on
analyticsadmin.googleapis.com — accountSummaries, property metadata — returns a Google HTML
404, not JSON. Two of three agents burned several attempts here, including trying to pass an
absolute URL (which gets concatenated into garbage).
To list properties, use treg, not the proxy:
treg connections resources <connection-id> # hits the Admin API server-side
Everything else
Standard GA4 Data API. runReport, runRealtimeReport, batchRunReports, runPivotReport,
checkCompatibility, /metadata all verified working through /call/. Two minor notes:
metric values are strings (cast before arithmetic), and metadata.timeZone governs what
"today" means (a property reports in its own timezone, e.g. Australia/Sydney).
⚠️ Reported but not observed here: high-cardinality dimensions can collapse into an (other) row.
Related skills
Generative Code Art
anthropics
Create algorithmic art with p5.js using randomness and interactive parameters.
Poster & Visual Design
anthropics
Create original posters and visual art in PNG and PDF formats.
Claude API Helper
anthropics
Build, debug, and optimize Claude API applications with caching and model migration support.
MCP Server Builder
anthropics
Build protocol servers that connect language models to external APIs and services.