gw-analytics

Files (1)

• SKILL.md

SKILL.md (first lines)

# Google Analytics 4

Read-only. Nothing here writes to a property.

## Invocation

```bash
CLI="python3 ${CLAUDE_PLUGIN_ROOT}/cli/gw.py"
```

## Scope prerequisite

GA4 is an opt-in scope, so a default `gw` token does not carry it. Add it once:

```bash
$CLI auth login --add-scopes analytics
```

`--add-scopes` unions with the scopes the account already has. Do not use `--scopes analytics`
here: a login replaces the token, so that form would drop Gmail, Calendar, Drive, Sheets, Docs,
Tasks and Forms. The scope granted is `analytics.readonly`.

## Commands

```bash
$CLI analytics properties --compact

$CLI analytics report --property PROPERTY_ID \
  [--metrics sessions,activeUsers] [--dimensions date,sessionDefaultChannelGroup] \
  [--since 28daysAgo] [--until yesterday] [--limit 100] [--offset 0] \
  [--order-by -sessions] [--filter hostname==example.com] [--totals] [--keep-empty-rows]

$CLI analytics realtime --property PROPERTY_ID [--metrics activeUsers] [--dimensions country]

$CLI analytics metadata --property PROPERTY_ID [--kind all|dimensions|metrics] [--grep TERM] [--full]

$CLI analytics check --property PROPERTY_ID [--metrics sessions] [--dimensions pagePath] [--suggest]
```

`--property` takes the numeric property id. The three ids that sit next to it in the GA4 UI are
each rejected by name rather than passed on to a confusing API error: `G-XXXXXXXXXX` is the
measurement id (the web tag), `GTM-XXXXXXX` is a Tag Manager container, and `UA-XXXXX-Y` is a
Universal Analytics property, which stopped collecting data in 2023 and is not reachable
through the GA4 API at all.

Dates accept `YYYY-MM-DD`, `today`, `yesterday` or `NdaysAgo`.

`--filter` is repeatable and clauses are ANDed: `dim==value`, `dim!=value`, `dim=~regex`,
`dim=@substring`.

`--order-by` takes a metric or a dimension you actually requested; prefix with `-` for
descending. Ordering by a field you did not request is rejected by name.

## Never guess a field name

A wrong dimension name is the most common way a GA4 call fails, and the failure is an opaque
400. Two cheap commands settle it before spending a call:

```bash
$CLI analytics metadata --property PROPERTY_ID --kind dimensions --grep channel --compact
$CLI analytics check --property PROPERTY_ID --metrics sessions --dimensions sessionDefaultChannelGroup
```

`sessionDefaultChannelGroup` is correct. `sessionDefaultChannelGrouping` does not exist; it is
widely copied from third-party skill packs and fails every time.

`check` answers about the fields **you named** and nothing else. The API itself judges every
field in the property against your request — around 490 of them, ~30KB — and a verdict drawn
from that is about fields you never asked for. Add `--suggest` when you do want that list,
which is the honest question it answers: *what else could I add to this request?*

## Response shapes (validated)

`properties`: `{"properties":[{"property_id","display_name","account","property_type"}],"count"}`
and, if a very large org pages past the ceiling, `"truncated":true` with a `"note"`.

`report` and `realtime` return flattened records, not the GA4 wire format:

```json
{"rows":[{"date":"20260901","sessionDefaultChannelGroup":"Organic Search","sessions":42}],
 "row_count":2,"returned":2,"dimensions":["date"],"metrics":["sessions"],
 "property":"properties/PROPERTY_ID","window":{"since":"7daysAgo","until":"yesterday"}}
```

Metric values are converted to numbers using the type the API declares, so rows sort and sum
without reparsing. Present when applicable: `totals`, `property_quota`, and these two, which
mean different things and are reported separately:

| Field | Meaning |
|---|---|
| `data_loss_from_other_row` | A high cardinality `(other)` row absorbed the tail, so the breakdown is incomplete. Re-run narrower, or use the BigQuery export. |
| `sampled` with `sampling` | The response was sampled. This is the only sampling signal. |

`metadata`: `{"property","dimensions":[...],"metrics":[...]}` — names only unless `--full`.

`check`: `{"property","dimensions":[{"name","compatibility"}],"metrics":[...],"compatible","incompatible":[...]}`
— one entry per field you named. `compatibility` is `COMPATIBLE`, `INCOMPATIBLE`, or
`UNKNOWN_FIELD` when the property does not carry that name at all. With `--suggest`, adds
`"could_add":{"dimensions":[...],"metrics":[...]}`.

A name that is not a GA4 field at all fails earlier, at the API, and the error carries a
correction: `Did you mean browserVersion? Field zzz is not a valid dimension.`

## Cheapest output for an agent

`--output csv` collapses a report to a header and rows, which is far smaller than the JSON
and is usually all an agent needs to answer a question:

```bash
$CLI --output csv analytics report --property PROPERTY_ID \
  --metrics sessions --dimensions date --since 7daysAgo
```

`--output` and `--fields` are **group-level** flags: they go **before** the subcommand.
`--compact` and `--account` go after it. `--fields rows` keeps only the rows key.

## Limits

GA4 accepts at most 9 dimensions per request, enforced before the call.

From Elnora-AI/elnora-google-workspace, Apache-2.0.

More from Elnora-AI/elnora-google-workspace