Google Analytics

Architecture

ga4 is a standalone Python CLI that wraps three GA4 APIs:

• Data API (v1beta + v1alpha) — ga4 data … — reporting, realtime, metadata, funnels, audience exports
• Admin API (v1beta + v1alpha) — ga4 admin … — accounts, properties, streams, key events, custom dims/metrics, measurement secrets, links, audiences, access bindings, annotations
• Measurement Protocol — ga4 mp … — event ingestion (send + validate against debug endpoint)

All commands emit JSON to stdout with indent=2. Errors go to stderr as plain text with exit 1. Destructive operations require --yes/-y on the CLI; the skill adds an additional user-confirmation layer (see Destructive operations below).

Auth is OAuth-user-only via ga4 auth login --client-secret <Desktop-OAuth-client.json>. The CLI owns its own state at ~/.config/skills/ga4/ (not under the skill's path — ga4 is usable outside this skill).

Before First Use

1. Install — uv sync --project /abs/path/to/skills/google-analytics
2. Create an OAuth Desktop client in GCP — https://console.cloud.google.com/apis/credentials → Create Credentials → OAuth client ID → Desktop app → download the JSON. ADC (gcloud auth application-default login) is deliberately not supported — Google is phasing out analytics scopes on the default gcloud client ID.
3. Auth — ga4 auth login --client-secret /path/to/downloaded.json. A browser opens for consent. On a headless machine, open an SSH tunnel first: ssh -L 8086:localhost:8086 <this-host> and open the printed URL on a machine with a browser. Scopes default to readonly + edit + manage-users; override with --scope (repeatable) for provision / user-deletion.
4. Grant GA access — in GA Admin → Access Management, add the Google account you just authed with as Viewer (reads) or Editor/Administrator (writes, user management). See references/setup.md for click-path.
5. Default property (optional, recommended) — ga4 config set-property 123456789.
6. Verify — ga4 doctor should be all-green.

Canonical invocation

uv run --project /path/to/skills/google-analytics ga4 <command> [args]

For brevity, examples below use ga4 directly. When running from outside the skill directory, always use the full uv run --project <abs-path> form.

Destructive operations

Before running any `delete` or `archive` subcommand, show the user the exact command (including target resource name) and ask for confirmation in conversation. Only pass `--yes/-y` after an affirmative answer in the current turn. Never chain multiple destructive ops without re-confirming each one.

The CLI's --yes flag is a non-interactive guardrail. The skill's job is to make sure a human explicitly agrees before a properties delete, key-events delete, custom-dimensions archive, custom-metrics archive, audiences archive, access-bindings delete, access-bindings batch-delete, annotations delete, data-streams delete, measurement-secrets delete, links firebase-delete, links ads-delete, links bigquery-delete, properties submit-user-deletion, or accounts delete is executed. If the user is in a hurry, still ask — a single clear confirmation is cheap compared to clobbering a production property.

Command index

ga4 auth, ga4 config, ga4 doctor

Property ids accept either 123456789 or properties/123456789.

ga4 data — Data API

Common run-report flags: --dimension-filter-json, --metric-filter-json, --order-by-json, --metric-aggregation, --cohort-spec-json, --comparisons-json, --limit, --offset, --currency-code, --keep-empty-rows, --return-property-quota, --request-json (full body override).

Filter/order/cohort JSON can be inline (--dimension-filter-json '{"filter":...}') or a file (--dimension-filter-json @/tmp/f.json). See references/data-api.md for the filter grammar.

ga4 admin accounts — Accounts

ga4 admin properties — Properties

ga4 admin data-streams, measurement-secrets

ga4 admin key-events, custom-dimensions, custom-metrics

ga4 admin links — Third-party links

ga4 admin audiences, access-bindings, annotations — all alpha

Alpha endpoints may change shape without notice; keep an eye on google-analytics-admin release notes if you script against them.

ga4 mp — Measurement Protocol

Single-event shortcut: --event-name purchase --event-params '{"value":12.34,"currency":"USD"}'. For Firebase/app streams, replace --measurement-id with --firebase-app-id. --endpoint eu routes through the EU regional endpoint.

MP limits (enforced locally before sending): 25 events/request, 40-char event names, 25 params/event. See references/admin-api.md for full limits including param value length.

Writing reports

# Last 7 days of active users by country
ga4 data run-report -p 123456789 -d country -m activeUsers -s 7daysAgo -e today

# Week-over-week comparison with two date ranges via request JSON
cat <<'EOF' > /tmp/wow.json
{
  "dimensions": [{"name": "deviceCategory"}],
  "metrics": [{"name": "engagementRate"}, {"name": "sessions"}],
  "date_ranges": [
    {"start_date": "7daysAgo",  "end_date": "yesterday", "name": "this_week"},
    {"start_date": "14daysAgo", "end_date": "8daysAgo",  "name": "last_week"}
  ]
}
EOF
ga4 data run-report -p 123456789 --request-json @/tmp/wow.json

# Filter: only mobile, only pages matching /blog/*
cat <<'EOF' > /tmp/filter.json
{"andGroup": {"expressions": [
  {"filter": {"fieldName": "deviceCategory", "stringFilter": {"value": "mobile"}}},
  {"filter": {"fieldName": "pagePath", "stringFilter": {"matchType": "BEGINS_WITH", "value": "/blog/"}}}
]}}
EOF
ga4 data run-report -p 123456789 -d pagePath -m sessions -s 7daysAgo -e today \
  --dimension-filter-json @/tmp/filter.json

For deep filter grammar (AND/OR/NOT, string/numeric/between/in-list filter types), the valid metric-aggregation set, cohort specs, and the "quota token" math, read references/data-api.md.

Admin safety

• Always `list`/`get` first before update/delete/archive. Validate you're targeting the right resource.
• Use `search-change-history` to audit recent changes before making new ones, and to find who made the last change to a resource.
• Alpha endpoints may change shape. If you get an unexpected schema error, check the google-analytics-admin package version and the alpha changelog.
• `update_mask` — most admin updates require a field mask. The CLI auto-computes it from flag-based updates, but for --body-json updates you must pass --update-mask explicitly.
• Scopes — the CLI requests the union of scopes its commands need. If a command 403s with "insufficient permissions", re-auth with a broader scope (see Before First Use).

Funnel / audience / access patterns

• Funnels (`run-funnel-report`) are built as an array of steps, each with a filter expression. The response has two sub-reports — funnel table and funnel visualization. See references/data-api.md for step-design patterns (sequential vs. any-order steps, breakdown dimensions, continuous vs. direct).
• Audiences (audiences create) have a deeply nested schema (filter clauses, scopes, sequences). Build the JSON separately and pass --body-json @audience.json. Start from an existing audience (audiences get) to see the shape.
• Access bindings use predefinedRoles/* role names. Common: predefinedRoles/no-cost-data, predefinedRoles/read-and-analyze, predefinedRoles/editor, predefinedRoles/admin. Changes at account scope apply to all properties.

Interpreting output

Engagement benchmarks, attribution model differences, funnel drop-off heuristics, audience sequence vs. condition patterns, realtime reporting caveats, and BigQuery long-term-storage tradeoffs are all in references/playbook.md. Read it before drawing conclusions about whether numbers are "good" — GA4's sampling and attribution defaults differ meaningfully from UA and from other analytics tools.

Troubleshooting

• "No credentials. Run: ga4 auth login …" — Exactly what it says. Get a Desktop OAuth client JSON from GCP and log in.
• "Permission denied" — The Google account you auth'd with doesn't have GA access. Grant Viewer/Editor in GA Admin → Access Management. Verify with ga4 admin accounts summaries-list.
• "Quota exhausted" — Pass --return-property-quota on a report to see live consumption. Data API tokens reset hourly/daily. GA360 gets 10x limits.
• "insufficient_scope" — The stored token was obtained with fewer scopes than this command needs. Re-run ga4 auth login --client-secret <path> --scope <extra-scope> (repeatable) to include them.
• "No property id" — Pass --property/-p, set GA_PROPERTY_ID, or ga4 config set-property <id>.
• Alpha schema changed — Pin google-analytics-admin and google-analytics-data in pyproject.toml, then uv sync.
• Realtime report is empty — The realtime window is only the last 30 minutes (60 for GA360). If there's genuinely no active traffic, the report will be empty; this is correct.
• MP send returned 2xx but the event didn't appear — mp send always returns 2xx regardless of validity. Use mp validate first to check for rejection reasons.

Configuration files

• ~/.config/skills/ga4/config.json — default property and other CLI settings
• ~/.config/skills/ga4/credentials.json — OAuth user creds (written by ga4 auth login)
• Override the config dir with GA4_CONFIG_DIR=/path/to/dir

Migrating from earlier versions

If upgrading from a build that stored config at ~/.config/ga4/, run ga4 config migrate --apply to move the credentials and config to the new location. ga4 auth status emits a deprecation_warning until the migration runs.