/common-metric-names

name: common-metric-names
description: "The correct GA4 Data API names for fields models most often get wrong. Use these before calling `get_ga4_data` — wrong names return a hard error."

Common Metric & Dimension Names

The correct GA4 Data API names for fields models most often get wrong. Use these before calling `get_ga4_data` — wrong names return a hard error.

> ⚠️ **YOUR TRAINING DATA IS OUTDATED**: Universal Analytics was sunset > 2023-07-01, and on 2024-05-06 Google Analytics 4 renamed all conversion metrics to **"key events"** > (`conversions` → `keyEvents`, `conversionRate` → `sessionKeyEventRate`). > Querying `conversions` will fail with an `Invalid metric` error. Always use `keyEvents`.

Metrics — correct API names

| What you mean | Wrong (will fail) | Correct API name | |---|---|---| | Goal completions / conversions (RENAMED 2024) | `conversions`, `goals`, `conversion` | `keyEvents` | | Total users | `users`, `totalVisitors` | `totalUsers` | | Active users (rolling 30-day ≈ MAU) | `MAU`, `monthlyActiveUsers`, `activeVisitors` | `active28DayUsers` | | Active users (rolling 7-day ≈ WAU) | `WAU`, `weeklyActiveUsers` | `active7DayUsers` | | Active users (rolling 1-day ≈ DAU) | `DAU`, `dailyActiveUsers` | `active1DayUsers` | | Distinct users in the queried range | `uniqueUsers` | `activeUsers` | | Page views | `pageViews`, `pageviews`, `page_views` | `screenPageViews` | | E-commerce purchases | `purchases`, `transactions` | `ecommercePurchases` | | Product views | `itemViews`, `productViews` | `itemsViewed` | | Items added to cart | `addToCarts`, `cartAdds` | `itemsAddedToCart` | | Revenue | `revenue`, `ecommerceRevenue` | `purchaseRevenue` | | Avg session duration | `avgSessionDuration`, `avgTimeOnSite` | `averageSessionDuration` | | Total engagement time | `engagementDuration`, `timeOnSite` | `userEngagementDuration` | | Session key event rate (was "conversion rate", renamed 2024) | `conversionRate`, `goalConversionRate`, `sessionConversionRate` | `sessionKeyEventRate` | | User key event rate | `userConversionRate` | `userKeyEventRate` | | Engaged sessions | `qualifiedSessions`, `validSessions` | `engagedSessions` | | Pages per session | `pagesPerSession`, `pageDepth` | `screenPageViewsPerSession` |

Dimensions — correct API names

| What you mean | Wrong (will fail) | Correct API name | |---|---|---| | Traffic channel group | `sessionDefaultChannelGrouping`, `channelGrouping` | `sessionDefaultChannelGroup` | | Landing page + query | `landingPage` (often wrong scope) | `landingPagePlusQueryString` | | Page path | `pagePath`, `page` | `pagePath` | | Page path + query | `pagePathPlusQueryString` | `unifiedPagePathScreen` | | Session source | `source` (wrong scope — see attribution-scope skill) | `sessionSource` | | Session medium | `medium` (wrong scope) | `sessionMedium` | | Device type | `device`, `deviceType` | `deviceCategory` | | Operating system | `os` | `operatingSystem` | | Browser | `userAgent` | `browser` | | Week of year | `week`, `weekNumber` | `week` (this one IS correct) |

Note on active users (MAU / WAU / DAU)

GA4 has no `MAU`, `WAU`, `DAU`, `monthlyActiveUsers`, or `dailyActiveUsers` metric — these hard-error. Use the rolling n-day metrics: `active1DayUsers` (≈ DAU), `active7DayUsers` (≈ WAU), `active28DayUsers` (≈ MAU). Each counts distinct users active in the N days *ending on that date* (a rolling window, not a calendar bucket). `activeUsers` = distinct users in the queried range. Never sum daily `activeUsers` across rows to get a period total — it double-counts users active on multiple days. For a monthly total, query `activeUsers` once over the whole range (no date dimension), or use `active28DayUsers` for a rolling month. Stickiness ratios `dauPerMau`, `dauPerWau`, `wauPerMau` are also available as metrics.

Note on bounce rate

GA4 bounce rate = sessions with NO engaged session (opposite of GA3 logic). A bounce rate of 60% means 60% of sessions had no engagement — that is high. In GA3, bounce rate meant single-page sessions. Do not compare GA3 and GA4 bounce rates.

When you hit a schema error

If `get_ga4_data` returns "Invalid dimension" or "Invalid metric", do not guess alternatives. Use `search_schema` with a keyword to find the correct name, or check this skill's table above.