GAGA4 MCPv2.11.9

Agent skill

Universal Analytics to GA4 Field Name Mapping

Universal Analytics (UA) was sunset on July 1, 2023. Language models trained on legacy documentation frequently guess deprecated UA field names (e.g., ga:sessions, pageviews, uniquePageviews, conversions) that cause hard 400 validation errors in the Google Analytics 4 Data API.

Additionally, on May 6, 2024, Google officially renamed conversions to key events across GA4. Use this mapping table to translate legacy dimensions and metrics into their valid GA4 Data API equivalents.

Metrics Mapping

Legacy UA Name (Invalid)GA4 Data API Name (Valid)TypeNotes
userstotalUsers or activeUsersMetricactiveUsers is GA4's primary user metric
pageviewsscreenPageViewsMetricTotal pages viewed across web and app
uniquePageviewsscreenPageViewsMetricGA4 does not track unique views; use sessions per page
avgSessionDurationaverageSessionDurationMetricAverage duration in seconds
timeOnPage / avgTimeOnPageuserEngagementDurationMetricTotal engagement time in seconds
conversions / goalCompletionsAllkeyEventsMetricRenamed from conversions on May 6, 2024
conversionRate / sessionConversionRatesessionKeyEventRateMetricPercentage of sessions with a key event
userConversionRateuserKeyEventRateMetricPercentage of users who triggered a key event
transactions / purchasesecommercePurchasesMetricNumber of completed e-commerce purchases
transactionRevenue / revenuepurchaseRevenueMetricTotal purchase revenue
revenuePerTransactionaveragePurchaseRevenueMetricAverage purchase revenue per transaction
itemQuantityitemsViewed or itemsPurchasedMetricSpecify viewed or purchased
entrancessessionsMetricUse session count with landingPage
bouncesbounceRateMetricGA4 calculates bounce rate as (1 - engagementRate)

Dimensions Mapping

Legacy UA Name (Invalid)GA4 Data API Name (Valid)ScopeNotes
channelGroupingsessionDefaultChannelGroupSessionOrganic Search, Direct, Paid, Referral
sourcesessionSourceSessionDomain or entity driving the session
mediumsessionMediumSessionorganic, cpc, referral, email
sourceMediumsessionSourceMediumSessionCombined source / medium
campaignsessionCampaignNameSessionUTM campaign name
keywordsessionManualTermSessionUTM term
landingPagePathlandingPageEventLanding page path without query parameters
pagePathpagePathEventPage path including directories
pageTitlepageTitleEventPage HTML title tag
deviceCategorydeviceCategoryEventdesktop, mobile, tablet
operatingSystemoperatingSystemEventiOS, Android, Windows, Macintosh
browserbrowserEventChrome, Safari, Firefox, Edge
countrycountryEventFull country name
citycityEventFull city name
userTypenewVsReturningUser'new' or 'returning'

The camelCase Syntax Rule

All GA4 Data API field names are strictly camelCase. Using snake_case will cause an invalid field error.

Wrong (snake_case)Correct (camelCase)
page_pathpagePath
session_sourcesessionSource
device_categorydeviceCategory
event_nameeventName
total_userstotalUsers
screen_page_viewsscreenPageViews

Attribution Scopes

GA4 splits attribution into three distinct scopes:

  1. Session Scope (session*): Attributes the visit (e.g., sessionSource, sessionMedium). Use for traffic acquisition.
  2. First User Scope (firstUser*): Attributes the person across their lifetime (e.g., firstUserSource). Use for user acquisition.
  3. Event Scope (no prefix): Attributes the specific action (e.g., pagePath, eventName). Use for page and event analytics.

Never mix user-scoped dimensions with session-scoped metrics in the same query. Consult the Compatible Combinations Guide for valid groupings.