/google-analytics

name: google-analytics
description: "[RU: ga4, гугл аналитика, аналитика 4] GA4 Data API v1beta — service account or OAuth. properties/{id}:runReport with dimensions, metrics, dateRanges, FilterExpression DSL (EXACT/CONTAINS/REGEXP, inList, numeric, between, and/or/not), orderBys, limit/offset. runRealtimeReport (30 min), runPivotReport, cohortSpec, batchRunReports (5-in-1). Admin API v1beta for customDimensions + conversionEvents. Token quotas per property and project. SKIP: Universal Analytics v3 sunset 2024-07 (→universal-analytics); Yandex.Metrika (→yandex-metrica); Search Console (→google-search-console); GTM (→google-tag-manager); BigQuery export (→bigquery); Cloud auth (→google-cloud-auth)."
stacks:
  - google-analytics
  - analytics
  - python
  - nodejs
tags:
  - analytics
  - google
  - ga4
  - reporting
  - oauth
  - marketing
source: vechkasov-global-skills
risk: high-stakes

<!-- versions:start -->

Version Requirements (May 2026)

**Primary pins:**

• GA4 Data API: `v1beta` (stable; base `https://analyticsdata.googleapis.com/v1beta/`)
• GA4 Admin API: `v1beta` (`https://analyticsadmin.googleapis.com/v1beta/`)
• Python client: `google-analytics-data >= 0.18`
• Node.js client: `@google-analytics/data ^4.x`
• Python: `3.14.x`
• Node.js: `24.x (Active LTS)`

> Source of truth: [STACK_VERSIONS.md](../../STACK_VERSIONS.md) — verified 2026-08-24

<!-- versions:end -->

Usage

Loaded automatically when its description matches the active task. Read only the section you need, then follow the link to the relevant reference file for full detail.

Use this skill when

• Programmatic pulls of GA4 data for dashboards: sessions, active users, conversions by source / channel / device
• Daily GA4 snapshot to PostgreSQL for SQL analytics and LTV calculations (aggregates, not event-level)
• Real-time traffic monitoring (last 30 min) for campaign launches, deployment monitoring, alerting
• Comparative reporting across multiple periods (multiple `dateRanges` in one request)
• Complex filtering: building `FilterExpression` with `andGroup` / `orGroup` / `notExpression`, `stringFilter` (EXACT, BEGINS_WITH, ENDS_WITH, CONTAINS, FULL_REGEXP, PARTIAL_REGEXP), `inListFilter`, `numericFilter`, `betweenFilter`
• Pivot reports (2D crosstabs: source x device, country x device)
• Cohort retention reports (`firstSessionDate` cohorts, DAILY/WEEKLY/MONTHLY granularity, `cohortActiveUsers`)
• Batch efficiency: packing 5 reports into one HTTP call via `batchRunReports`
• Configuration: listing properties, custom dimensions, conversion events via Admin API v1beta
• Token budget monitoring (`returnPropertyQuota: true` and reading `PropertyQuota` in the response)
• Backend authorization: service account granted access via Admin -> Property -> Property Access Management

Do not use this skill when

• Universal Analytics (UA, `UA-XXXXX`) — sunset 2024-07-01, API disabled. Migration is not "switch the ID"; semantics differ (sessions vs events, dimensions, attribution). Move the account to GA4 first.
• Event-level export (millions of raw rows) — Data API returns aggregates; for raw events use BigQuery Export GA4 (cascade -> `bigquery`)
• Russian analog of GA4 — `yandex-metrica` (cascade -> `yandex-metrica`); a different dimension / metric universe
• Search Console data (CTR / impressions / positions) — `google-search-console` (cascade)
• Managing containers / triggers / tags — Google Tag Manager API, `google-tag-manager` (cascade)
• Generic Google Cloud auth setup (service account creation, key issuance, `gcloud auth`) — `google-cloud-auth` (cascade)
• A/B testing inside GA4 — either GTM + Optimize (deprecated) or a dedicated feature flag service
• Writing data into GA4 — Data API is read-only; for event writes use Measurement Protocol (different API)
• Parsing the GA4 UI (Explorations, default Acquisition / Engagement reports) — Data API does not mirror UI reports 1:1; build the slice yourself

Purpose

Google Analytics Data API v1beta is the official programmatic surface for GA4. It returns the same aggregates the UI shows. Five core reporting methods: `runReport` (standard), `runRealtimeReport` (last 30 min), `runPivotReport` (crosstabs), `batchRunReports` (5 reports in 1 call), `runReport` with `cohortSpec` (cohort analysis). Admin API v1beta covers configuration (properties, customDimensions, conversionEvents). Auth: OAuth 2.0 (user consent) or service account (backend).

This skill is **high-stakes** because:

1. **Property ID is not Measurement ID.** `properties/123456789` is the numeric ID from Admin -> Property Settings. `G-XXXXXXX` is a data stream Tag ID and **will not work** in the API. `properties/G-XXX:runReport` returns 400 INVALID_ARGUMENT. 2. **The service account must be explicitly granted in Property Access Management** on the GA4 side. Holding a key file is not enough; without a Viewer / Analyst grant the API returns 403 PERMISSION_DENIED. Google emails the service account automatically. 3. **Token quota is consumed by complex requests.** Standard property: 200,000 tokens/day, 40,000/hour; per-project-per-property 14,000/hour. Long date range x many dimensions x high cardinality (`pagePath`, `eventName`) x filters can cost tens of tokens per call. Enable `returnPropertyQuota: true` and log it. 4. **Sampling can occur.** GA4 samples when event volume exceeds thresholds (different from UA, plan-dependent). Signals: `metadata.samplingMetadatas` and `metadata.dataLossFromOtherRow`. The UA 360 "no sampling" assumption does not port 1:1. 5. **dimensionFilter vs metricFilter.** `dimensionFilter` runs before aggregation (SQL WHERE), `metricFilter` after (SQL HAVING). Swapping them yields empty or surprising results. 6. **Realtime supports a limited dimension / metric set.** Many historical dimensions are missing; check the realtime metadata before authoring. 7. **`runReport` row limits:** default 10,000, max 250,000. For larger slices use `offset` / `limit` pagination or split by `date