8.7k superdesigndev

google-analytics Skill

通过 treg 查询 Google Analytics 4 时要避开的坑——GA4 Data API 返回看似自信却错误的结果而非报错的情况。回答来自 GA4 的网站流量、访客、浏览量、渠道、转化或收入问题时都应使用。

安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。

查看源码

技能指令原文(SKILL.md)

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.

  • API schema: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema
  • runReport: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport
  • Quotas: https://developers.google.com/analytics/devguides/reporting/data/v1/quotas

配合站内内容