Data reference - Adriel Knowledge Base

Introduction

Google Analytics 4 (GA4) is the current generation of Google’s web and app analytics platform. It replaces Universal Analytics with an event-based data model — every user interaction (page view, scroll, click, purchase) is recorded as an event with parameters, rather than being bucketed into the older pageview / session schema. GA4 measures users and sessions across web and mobile properties, supports cookieless measurement modes, and exposes both standard and custom events. The connector reads from the Google Analytics Data API (queries) and the Google Analytics Admin API (account, property, and metadata discovery). One data source is created per GA4 Property; connecting three properties produces three independent data sources. Available metrics and breakdowns — including any custom breakdowns or custom metrics defined in the property — are discovered dynamically from the GA4 Metadata API and surfaced in the field picker. As an analytics connector, session, event, and breakdown data are standardized so widgets can aggregate alongside ad-platform sources without additional configuration. To connect this data source, see How to connect Google Analytics 4 to Adriel.

Data refresh strategy

Architecture data

Architecture covers the GA4 Account → Property → Data stream hierarchy plus the per-property metadata catalog (standard breakdowns, standard metrics, custom breakdowns, custom metrics, channel groups). The metadata catalog is fetched from the GA4 Metadata API and cached for 12 hours per (account, property) pair. Newly defined custom breakdowns or custom metrics can therefore take up to 12 hours to appear in the field picker.

Reports data

Reports data is fetched on demand. Each dashboard load issues a live request to the GA4 Data API for the selected date range, breakdowns, metrics, and filters — there is no nightly snapshot or fixed refresh window. Returned rows reflect GA4’s current processing state; GA4 typically considers data for the prior day fully processed within 24–48 hours, so very recent rows may still shift slightly (Google Analytics Help — Data freshness). An internal cache accelerates recent queries: the last 3 days are re-fetched on each refresh cycle, and up to ~6 months of historical results are retained. Older ranges are always requested live from GA4. Sampling and the per-query row cap apply at request time (see Limitations).

Architecture levels

Account → Property → Data stream GA4 has no ad-hierarchy analog. A GA4 Property is the reporting boundary; Data streams (web, iOS app, Android app) feed events into the Property.

Date range limits

Breakdown	Max range
Daily	93 days
Weekly	1 year
Monthly	2 years

GA4 has no connector-side hard cap on the date range for a single query, but sampling likelihood and row-cap risk rise sharply with wider ranges. The values above are workspace defaults; wider queries succeed when the property’s event volume is low.

Metrics

How to read the columnsCode style like sessions is the literal GA4 Data API field name (from the property’s metadata catalog). Italic text describes how a value is produced when it doesn’t map cleanly to a single GA4 field or when it’s computed by Adriel.Data type vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean.

Sessions & users

Metric	Description	Data type	API Key
Sessions	Sessions started (from `session_start` events).	Number	`sessions`
Sessions per user	Sessions divided by active users.	Ratio	`sessionsPerUser`
Active users	Distinct users who visited the site or app.	Number	`activeUsers`
Active 7-day users	Distinct active users in a 7-day window ending on the report’s last day.	Number	`active7DayUsers`
Active 28-day users	Distinct active users in a 28-day window ending on the report’s last day.	Number	`active28DayUsers`
New users	First-time visitors (from `first_open` / `first_visit`).	Number	`newUsers`
Total users	Distinct users with 1+ event in the range.	Number	`totalUsers`
DAU / MAU	Rolling percentage of 30-day actives who are also 1-day actives.	Percentage	`dauPerMau`
DAU / WAU	Rolling percentage of 7-day actives who are also 1-day actives.	Percentage	`dauPerWau`
WAU / MAU	Rolling percentage of 30-day actives who are also 7-day actives.	Percentage	`wauPerMau`

Engagement

Metric	Description	Data type	API Key
Engaged sessions	Sessions lasting ≥10s, with a key event, or with 2+ screen/page views.	Number	`engagedSessions`
Engagement rate	Engaged sessions divided by sessions.	Percentage	`engagementRate`
Bounce rate	Share of sessions that were not engaged (1 − engagement rate).	Percentage	`bounceRate`
Average session duration	Mean session length.	Duration	`averageSessionDuration`
User engagement duration	Total time users actively engaged (foreground time).	Duration	`userEngagementDuration`
Page views	Total `page_view` • `screen_view` events.	Number	`screenPageViews`
Page views per session	Page views divided by sessions.	Ratio	`screenPageViewsPerSession`
Page views per user	Page views divided by active users.	Ratio	`screenPageViewsPerUser`
Scrolled users	Unique users scrolling to 90%+ of a page.	Number	`scrolledUsers`

Events

Metric	Description	Data type	API Key
Event count	Total events in the range.	Number	`eventCount`
Event count per user	Event count divided by active users.	Ratio	`eventCountPerUser`
Events per session	Event count divided by sessions.	Ratio	`eventsPerSession`
Event value	Sum of the `value` event parameter.	Number	`eventValue`

Conversions (key events)

Metric	Description	Data type	API Key
Key events	Count of key events (some are default, e.g. `first_open`, `purchase`).	Number	`keyEvents`
Session key event rate	Share of sessions that triggered any key event.	Percentage	`sessionKeyEventRate`
User key event rate	Share of users that triggered any key event.	Percentage	`userKeyEventRate`
Key events: Purchase	Key-event count filtered to `purchase`.	Number	Adriel-scoped alias of `keyEvents`* (`purchase` only)*
Session key event rate: Purchase	Session key-event rate filtered to `purchase`.	Percentage	Adriel-scoped alias of `sessionKeyEventRate`
User key event rate: Purchase	User key-event rate filtered to `purchase`.	Percentage	Adriel-scoped alias of `userKeyEventRate`

Purchase-scoped key-event helpersThe “Key events: Purchase”, “Session key event rate: Purchase”, and “User key event rate: Purchase” metrics are Adriel-scoped aliases that pre-filter the underlying GA4 keyEvents, sessionKeyEventRate, and userKeyEventRate fields to the purchase event. GA4 itself exposes only the unfiltered fields.

Ecommerce revenue

Metric	Description	Data type	API Key
Total revenue	Purchase + subscription + ad revenue, minus refunds.	Currency	`totalRevenue`
Purchase revenue	Net purchase revenue after refunds.	Currency	`purchaseRevenue`
Gross purchase revenue	Purchase and subscription revenue before refunds.	Currency	`grossPurchaseRevenue`
Refund amount	Sum of `refund` and `app_store_refund` revenue.	Currency	`refundAmount`
Item revenue	Net item revenue after refunds; excludes tax and shipping.	Currency	`itemRevenue`
Gross item revenue	Item price × quantity, pre-refund; excludes tax and shipping.	Currency	`grossItemRevenue`
Item refund amount	Refunded item revenue (price × quantity on the refund event).	Currency	`itemRefundAmount`
Item discount amount	Item-level discounts recorded on ecommerce events.	Currency	`itemDiscountAmount`
Shipping amount	Value of the `shipping` parameter on transactions.	Currency	`shippingAmount`
Tax amount	Value of the `tax` parameter on transactions.	Currency	`taxAmount`
Average purchase revenue	Average revenue per transaction.	Currency	`averagePurchaseRevenue`
Average purchase revenue per user	Average purchase revenue per active user.	Currency	`averagePurchaseRevenuePerUser`
Average purchase revenue per paying user (ARPPU)	Average purchase revenue per paying user.	Currency	`averagePurchaseRevenuePerPayingUser`
Average revenue per user (ARPU)	Average revenue per active user (uses Total revenue including AdMob).	Currency	`averageRevenuePerUser`

Ecommerce funnel

Metric	Description	Data type	API Key
Add-to-cart events	Times users added items to cart.	Number	`addToCarts`
Items added to cart	Units in `add_to_cart` events.	Number	`itemsAddedToCart`
Checkouts	Times users started checkout (`begin_checkout`).	Number	`checkouts`
Items checked out	Units in `begin_checkout` events.	Number	`itemsCheckedOut`
Item views	`view_item` event count.	Number	`itemViewEvents`
Items viewed	Units in `view_item` events.	Number	`itemsViewed`
Item list views	`view_item_list` event count.	Number	`itemListViewEvents`
Items viewed in list	Units in `view_item_list` events.	Number	`itemsViewedInList`
Item list clicks	`select_item` event count.	Number	`itemListClickEvents`
Items clicked in list	Units in `select_item` events.	Number	`itemsClickedInList`
Item list click-through rate	List-select users divided by list-view users.	Percentage	`itemListClickThroughRate`
Promotion views	`view_promotion` event count.	Number	`promotionViews`
Items viewed in promotion	Units in `view_promotion` events.	Number	`itemsViewedInPromotion`
Promotion clicks	`select_promotion` event count.	Number	`promotionClicks`
Items clicked in promotion	Units in `select_promotion` events.	Number	`itemsClickedInPromotion`
Item promotion click-through rate	Promo-select users divided by promo-view users.	Percentage	`itemPromotionClickThroughRate`
Cart-to-view rate	Users who added a product divided by users who viewed a product.	Percentage	`cartToViewRate`
Purchase-to-view rate	Users who purchased divided by users who viewed a product.	Percentage	`purchaseToViewRate`
Transactions	Count of transaction events with revenue.	Number	`transactions`
Transactions per purchaser	Average transactions per purchaser.	Ratio	`transactionsPerPurchaser`
Items purchased	Units in purchase events.	Number	`itemsPurchased`
Ecommerce purchases	Count of `purchase` events (excludes in-app and subscription purchases).	Number	`ecommercePurchases`
Total purchasers	Distinct users logging purchase events in the period.	Number	`totalPurchasers`
First-time purchasers	Users completing their first purchase event.	Number	`firstTimePurchasers`
First-time purchaser rate	Share of active users who made a first purchase.	Percentage	`firstTimePurchaserRate`
First-time purchasers per new user	Average first-time purchasers per new user.	Ratio	`firstTimePurchasersPerNewUser`
Purchaser rate	Share of active users making 1+ purchases.	Percentage	`purchaserRate`

Advertising (linked accounts)

Metric	Description	Data type	API Key
Advertiser ad cost	Total ad spend imported from linked Google Ads.	Currency	`advertiserAdCost`
Advertiser ad clicks	Total ad clicks (includes linked SA360 imports).	Number	`advertiserAdClicks`
Advertiser ad impressions	Total ad impressions (includes DV360 imports).	Number	`advertiserAdImpressions`
Advertiser ad cost per click (CPC)	Ad cost divided by ad clicks.	Currency	`advertiserAdCostPerClick`
Advertiser ad cost per key event	Ad cost divided by key events.	Currency	`advertiserAdCostPerKeyEvent`
Return on ad spend (ROAS)	Total revenue divided by advertiser ad cost.	Ratio	`returnOnAdSpend`
Publisher ad clicks	`ad_click` event count.	Number	`publisherAdClicks`
Publisher ad impressions	`ad_impression` event count.	Number	`publisherAdImpressions`
Total ad revenue	AdMob and third-party ad revenue combined.	Currency	`totalAdRevenue`
Ad unit exposure	Time an ad unit was exposed (milliseconds).	Duration	`adUnitExposure`

Organic search (Search Console link)

Metric	Description	Data type	API Key
Organic Google Search clicks	Organic clicks imported from a linked Search Console property.	Number	`organicGoogleSearchClicks`
Organic Google Search impressions	Organic impressions from Search Console.	Number	`organicGoogleSearchImpressions`
Organic Google Search CTR	Organic clicks divided by organic impressions.	Percentage	`organicGoogleSearchClickThroughRate`
Organic Google Search average position	Average SERP position for the property (requires Search Console link).	Number	`organicGoogleSearchAveragePosition`

App stability

Metric	Description	Data type	API Key
Crash-affected users	Users who logged an `app_exception` event.	Number	`crashAffectedUsers`
Crash-free users rate	Users without crashes divided by total users.	Percentage	`crashFreeUsersRate`

Custom metrics

Custom metrics defined in the GA4 property are exposed automatically once the metadata cache refreshes.

Metric	Description	Data type	API Key
Any custom metric	Property-defined metric surfaced by the GA4 Metadata API.	Number	The key reflects the custom metric configured in GA4.

Breakdowns

How to read the columnsCode style like sessionSource is the literal GA4 Data API field name. Italic text describes how a value is produced when it doesn’t map cleanly to a single GA4 field or when it’s produced by Adriel.

Traffic source (event-scoped)

Breakdown	Description	API Key
Source	Source attributed to the key event.	`source`
Medium	Medium attributed to the key event.	`medium`
Source / medium	Combined source and medium string.	`sourceMedium`
Campaign ID	Marketing campaign identifier attributed to the event.	`campaignId`
Campaign name	Marketing campaign name attributed to the event.	`campaignName`
Default channel group	Channel group derived from source and medium (Direct, Organic Search, Paid Search, Paid Social, Organic Social, Email, Affiliates, Referral, Video, Display).	`defaultChannelGroup`
Primary channel group	Channel group used in standard GA4 reports (active record over time).	`primaryChannelGroup`

Attribution scope: event, session, and first-user variantsGA4 exposes three attribution scopes for traffic-source breakdowns. Event-scoped breakdowns (above) attribute each event to the source active at the time of the event. Session-scoped breakdowns attribute all events in a session to the source that started the session. First-user (acquisition-scoped) breakdowns attribute events to the source that originally acquired the user. Choosing a different scope will change reported totals for the same date range — this is expected, not a discrepancy.

Traffic source (session-scoped)

Breakdown	Description	API Key
Session source	Source that started the session.	`sessionSource`
Session medium	Medium that started the session.	`sessionMedium`
Session source / medium	Combined source and medium for the session.	`sessionSourceMedium`
Session campaign ID	Marketing campaign ID for the session.	`sessionCampaignId`
Session campaign name	Marketing campaign name for the session.	`sessionCampaignName`
Session default channel group	GA4 default channel grouping for the session.	`sessionDefaultChannelGroup`

Traffic source (first-user / acquisition)

Breakdown	Description	API Key
First user source	Source that first acquired the user.	`firstUserSource`
First user medium	Medium that first acquired the user.	`firstUserMedium`
First user source / medium	Combined source and medium of first acquisition.	`firstUserSourceMedium`
First user source platform	Platform that first drove traffic.	`firstUserSourcePlatform`
First user campaign ID	Marketing campaign ID at first acquisition.	`firstUserCampaignId`
First user campaign name	Marketing campaign name at first acquisition.	`firstUserCampaignName`
First user default channel group	Channel grouping at first acquisition.	`firstUserDefaultChannelGroup`
First user primary channel group	Primary channel group at first acquisition.	`firstUserPrimaryChannelGroup`

Manual UTM tagging

Breakdown	Description	API Key
Manual source	Value of `utm_source`.	`manualSource`
Manual medium	Value of `utm_medium`.	`manualMedium`
Manual source / medium	Combined source and medium.	`manualSourceMedium`
Manual campaign name	Value of `utm_campaign`.	`manualCampaignName`
Manual campaign ID	Value of `utm_id`.	`manualCampaignId`
Manual ad content	Value of `utm_content`.	`manualAdContent`
Manual term	Value of `utm_term`.	`manualTerm`
Manual source platform	Value of `utm_source_platform`.	`manualSourcePlatform`
Manual creative format	Value of `utm_creative_format`.	`manualCreativeFormat`
Manual marketing tactic	Value of `utm_marketing_tactic` (e.g. remarketing, prospecting).	`manualMarketingTactic`

Linked Google Ads

Breakdown	Description	API Key
Google Ads account name	Linked Google Ads account (`customer.descriptive_name`).	`googleAdsAccountName`
Google Ads customer ID	Linked Google Ads customer ID.	`googleAdsCustomerId`
Google Ads campaign name	Linked Google Ads campaign name.	`googleAdsCampaignName`
Google Ads campaign ID	Linked Google Ads campaign identifier.	`googleAdsCampaignId`
Google Ads campaign type	Search, Display, Shopping, Video, Demand Gen, App, Smart, Hotel, Local, Performance Max.	`googleAdsCampaignType`
Google Ads ad network type	Google search, Search partners, Google Display Network, YouTube Search, YouTube Videos, Cross-network, Social.	`googleAdsAdNetworkType`
Google Ads ad group name	Linked Google Ads ad group name.	`googleAdsAdGroupName`
Google Ads ad group ID	Linked Google Ads ad group identifier.	`googleAdsAdGroupId`
Google Ads creative ID	Creative identifier.	`googleAdsCreativeId`
Google Ads keyword	Matched keyword that led to the key event.	`googleAdsKeyword`
Google Ads query	Search query that led to the key event.	`googleAdsQuery`

First-user variants of every Google Ads breakdown above are also exposed under firstUserGoogleAds… (e.g. firstUserGoogleAdsCampaignName) and represent the Google Ads field that originally acquired the user.

Linked Search Ads 360 (SA360)

Breakdown	Description	API Key
SA360 manager account name / ID	Top of the SA360 hierarchy.	`sa360ManagerAccountName`, `sa360ManagerAccountId`
SA360 engine account name / ID / type	Engine-level account (Google, Bing, Yahoo, etc.).	`sa360EngineAccountName`, `sa360EngineAccountId`, `sa360EngineAccountType`
SA360 campaign name / ID	SA360 campaign.	`sa360CampaignName`, `sa360CampaignId`
SA360 ad group name / ID	SA360 ad group.	`sa360AdGroupName`, `sa360AdGroupId`
SA360 creative format	Creative format used.	`sa360CreativeFormat`
SA360 keyword text	Keyword that matched the search query.	`sa360KeywordText`
SA360 query	Search query typed by the user.	`sa360Query`
SA360 source / medium	Where the search happened and the payment mode.	`sa360Source`, `sa360Medium`, `sa360SourceMedium`

First-user variants of every SA360 breakdown are also exposed under firstUserSa360….

Linked Display & Video 360 (DV360)

Breakdown	Description	API Key
DV360 partner name / ID	Agency, trading desk, or large individual advertiser.	`dv360PartnerName`, `dv360PartnerId`
DV360 advertiser name / ID	Real-life business running the campaign.	`dv360AdvertiserName`, `dv360AdvertiserId`
DV360 campaign name / ID	Group of related insertion orders.	`dv360CampaignName`, `dv360CampaignId`
DV360 insertion order name / ID	Set of line items in the same campaign.	`dv360InsertionOrderName`, `dv360InsertionOrderId`
DV360 line item name / ID	Bids on impressions and serves creatives.	`dv360LineItemName`, `dv360LineItemId`
DV360 creative name / ID / format	Creative used to serve the impression.	`dv360CreativeName`, `dv360CreativeId`, `dv360CreativeFormat`
DV360 exchange name / ID	Exchange the impression was purchased through.	`dv360ExchangeName`, `dv360ExchangeId`
DV360 source / medium	Site name and billable outcome (e.g. cpm).	`dv360Source`, `dv360Medium`, `dv360SourceMedium`

First-user variants of every DV360 breakdown are also exposed under firstUserDv360….

Linked Campaign Manager 360 (CM360)

Breakdown	Description	API Key
CM360 account / advertiser	CM360 account and advertiser identifiers and names.	`cm360AccountId`, `cm360AccountName`, `cm360AdvertiserId`, `cm360AdvertiserName`
CM360 campaign	CM360 campaign identifier and name.	`cm360CampaignId`, `cm360CampaignName`
CM360 placement	Placement identifier, name, and cost structure (e.g. ‘CPM’).	`cm360PlacementId`, `cm360PlacementName`, `cm360PlacementCostStructure`
CM360 creative	Creative identifier, name, format, type, type ID, version, and rendering ID.	`cm360CreativeId`, `cm360CreativeName`, `cm360CreativeFormat`, `cm360CreativeType`, `cm360CreativeTypeId`, `cm360CreativeVersion`, `cm360RenderingId`
CM360 site	Site where the ad space was purchased.	`cm360SiteId`, `cm360SiteName`
CM360 source / medium	Site name and cost structure.	`cm360Source`, `cm360Medium`, `cm360SourceMedium`

First-user and session-scoped variants of every CM360 breakdown are also exposed under firstUserCm360… and sessionCm360… respectively.

Page & content

Breakdown	Description	API Key
Page path	URL portion between hostname and query string.	`pagePath`
Page path + query string	URL following the hostname, including the query.	`pagePathPlusQueryString`
Page location	Protocol + host + path + query (populated by `page_location`).	`pageLocation`
Full page URL	Hostname + page path + query string.	`fullPageUrl`
Page title	Title of the page viewed.	`pageTitle`
Host name	Subdomain + domain.	`hostName`
Landing page	Page path of the first pageview in a session.	`landingPage`
Landing page + query string	Path and query of the first pageview.	`landingPagePlusQueryString`
Page referrer	Full referring URL (populated by `page_referrer`).	`pageReferrer`
Percent scrolled	Percentage down the page scrolled (Enhanced Measurement).	`percentScrolled`
Content group	Category applied to items of published content.	`contentGroup`
Content ID	Identifier of the selected content.	`contentId`
Content type	Category of the selected content.	`contentType`
Search term	Term searched by the user (Enhanced Measurement).	`searchTerm`

Event

Breakdown	Description	API Key
Event name	Name of the event.	`eventName`
Is key event	`true` if the event is marked as a key event. Marking a key event only affects reports from creation time forward.	`isKeyEvent`
Method	Method by which an event was triggered.	`method`

Link & file interactions (Enhanced Measurement)

Breakdown	Description	API Key
Outbound	`true` if the link led to a site outside the property’s domain.	`outbound`
Link URL / domain / classes / ID / text	Full URL, destination domain, HTML class, HTML id, and link text for outbound links or downloads.	`linkUrl`, `linkDomain`, `linkClasses`, `linkId`, `linkText`
File name	Page path of the downloaded file.	`fileName`
File extension	Extension of the downloaded file (e.g. pdf, txt).	`fileExtension`

Ecommerce item

Breakdown	Description	API Key
Item ID / name / brand / variant	Item identifier, display name, brand, and variant (size, color, etc.).	`itemId`, `itemName`, `itemBrand`, `itemVariant`
Item category / category 2–5	Item’s hierarchical category path (e.g. Apparel > Mens > Summer > Shirts > T-shirts).	`itemCategory`, `itemCategory2`, `itemCategory3`, `itemCategory4`, `itemCategory5`
Item list ID / name / position	List the item appeared in.	`itemListId`, `itemListName`, `itemListPosition`
Item promotion ID / name	Promotion identifier and display name.	`itemPromotionId`, `itemPromotionName`
Item promotion creative name / slot	Creative name and slot for the promotion.	`itemPromotionCreativeName`, `itemPromotionCreativeSlot`
Item affiliation	Name or code of the affiliate associated with the item.	`itemAffiliation`
Item location ID	Physical location (Google Place ID recommended).	`itemLocationID`
Order coupon	Order-level coupon code.	`orderCoupon`
Currency code	Local ISO 4217 currency of the ecommerce event.	`currencyCode`

Device & platform

Breakdown	Description	API Key
Device category	desktop / mobile / tablet.	`deviceCategory`
Device model	Specific device model (e.g. iPhone 10,6).	`deviceModel`
Mobile device branding	Manufacturer or brand (Samsung, HTC, etc.).	`mobileDeviceBranding`
Mobile device marketing name	Branded device name (Galaxy S10, P30 Pro).	`mobileDeviceMarketingName`
Mobile device model	Mobile device model name (iPhone X, SM-G950F).	`mobileDeviceModel`
Operating system	Operating system name.	`operatingSystem`
Operating system version	Operating system version.	`operatingSystemVersion`
Operating system + version	Combined OS and version.	`operatingSystemWithVersion`
Platform	web / iOS / Android.	`platform`
Platform + device category	Platform and device type combined (e.g. Android / mobile).	`platformDeviceCategory`
Browser	Browser used to view the site.	`browser`
Screen resolution	Resolution of the user’s monitor.	`screenResolution`
Language	Language setting of the user’s browser or device.	`language`
Language code	ISO 639 language code (e.g. en-us).	`languageCode`

App

Breakdown	Description	API Key
App version	App’s versionName (Android) or short bundle version (iOS).	`appVersion`
Ad source name	Source network that served the ad (AdMob Network, Liftoff, Facebook Audience Network, etc.).	`adSourceName`
Ad format	How the ad looked and where it was placed (Interstitial, Banner, Rewarded, Native advanced).	`adFormat`
Ad unit name	Name of the ad unit container placed in the app.	`adUnitName`
Achievement ID	Achievement identifier for gaming events.	`achievementId`
Character	Player character in a game.	`character`
Group ID	Player group identifier in a game.	`groupId`
Level	Player’s level in a game.	`level`

Geography

Breakdown	Description	API Key
Continent	Continent of user activity (Americas, Asia, etc.).	`continent`
Continent ID	Geographic ID of the continent, derived from IP.	`continentId`
Country	Country of the user.	`country`
Country ID	ISO 3166-1 alpha-2 country code, derived from IP.	`countryId`
Region	Geographic region derived from IP address.	`region`
City	City of the user.	`city`
City ID	Geographic ID of the city, derived from IP.	`cityId`

Region breakdown: non-US fallbackThe Region breakdown maps cleanly to US states for users with countryId = 'US'. Rows from other countries — and US rows where the region does not match GA4’s USStates map — surface as others when rendered on the US-state map widget.

Audience

Breakdown	Description	API Key
New vs returning	`new` (0 previous sessions) or `returning` (1+ previous sessions).	`newVsReturning`
Audience ID	Numeric identifier of a GA4 Audience.	`audienceId`
Audience name	Given name of the Audience.	`audienceName`
Audience resource name	Resource name of the Audience.	`audienceResourceName`
Branding interest	Interests demonstrated by users higher in the shopping funnel (Shoppers, Lifestyles & Hobbies, Travel, etc.). Users can be counted in multiple categories.	`brandingInterest`
First session date	Date the user’s first session occurred (YYYYMMDD).	`firstSessionDate`

Time

Breakdown	Description	API Key
Date	Date of the event (YYYYMMDD).	`date`
Date hour	Combined date and hour (YYYYMMDDHH).	`dateHour`
Date hour minute	Combined date, hour, and minute (YYYYMMDDHHMM).	`dateHourMinute`
Day	Day of the month (01–31).	`day`
Day of week	Integer day of the week (0 = Sunday).	`dayOfWeek`
Day of week name	Day of the week in English.	`dayOfWeekName`
Hour	Two-digit hour of the day (0–23) in the property’s timezone.	`hour`
Minute	Two-digit minute of the hour (0–59).	`minute`
Month	Two-digit month of the event (01–12).	`month`
ISO week	ISO week number (Monday-start).	`isoWeek`
ISO year	ISO year of the event.	`isoYear`
ISO year + week	Combined ISO year and week (e.g. 201652).	`isoYearIsoWeek`
Nth day / hour / minute / week / month / year	Count since the start of the date range.	`nthDay`, `nthHour`, `nthMinute`, `nthWeek`, `nthMonth`, `nthYear`

Time & date grouping

Adriel groups GA4’s daily-granularity results into these standard views for reporting alongside other connectors.

Breakdown	Description
Auto Time Breakdown	Automatically picks the best granularity for the date range.
Daily	Split reports by day.
Weekly (Start: Mon)	Split reports by ISO week, starting Monday.
Weekly (Start: Sun)	Split reports by week, starting Sunday.
Week Date Breakdown	Split by the start date of each week.
Week Number Breakdown (W#)	Split by week number in the year.
Monthly	Split reports by calendar month.
Quarterly	Split reports by calendar quarter.
Yearly	Split reports by calendar year.

Custom breakdowns

Custom breakdowns defined in the GA4 property are exposed automatically once the metadata cache refreshes.

Breakdown	Description	API Key
Any custom breakdown	Property-defined breakdown surfaced by the GA4 Metadata API.	The key reflects the custom breakdown configured in GA4.

Limitations

Based on the current connector, Google Analytics 4 has:

A 100,000-row cap per single query — wider results are truncated and a GA_ROW_LIMIT warning is raised.
Sampling on high-volume queries — the connector surfaces the sampling percentage as a GA_SAMPLED_DATA warning; sampled results are estimates. Sampling likelihood rises with wider date ranges, more breakdowns, or high-traffic properties (Google Analytics Help — Data sampling).
High-cardinality “(other)” row folding — GA4 folds high-cardinality breakdowns into a single (other) row once its per-property cardinality limits are exceeded (Google Analytics Help — Cardinality and (other) rows). This is a GA4 processing behavior, not a connector behavior.
No cohort fields — GA4 breakdowns and metrics whose API name contains cohort are excluded from the field picker.
A 12-hour lag on newly defined custom fields — property metadata is cached for 12 hours; new custom breakdowns and metrics only appear after the cache refreshes.
A rate limit of 9 concurrent calls per second per Property — higher volumes are queued and processed sequentially.
A ~6-month history cap on the internal report cache — older ranges are always fetched live from GA4.
API-layer thresholding — for privacy reasons GA4 may withhold rows with very small user counts; those rows do not appear even in unsampled queries (Google Analytics Help — Data thresholds).
Read-only OAuth scope — the connector requests analytics.readonly and cannot write back to GA4.
One data source per GA4 Property — connecting an Account provisions one Adriel data source per Property selected under it.

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Metrics

​Sessions & users

​Engagement

​Events

​Conversions (key events)

​Ecommerce revenue

​Ecommerce funnel

​Advertising (linked accounts)

​Organic search (Search Console link)

​App stability

​Custom metrics

​Breakdowns

​Traffic source (event-scoped)

​Traffic source (session-scoped)

​Traffic source (first-user / acquisition)

​Manual UTM tagging

​Linked Google Ads

​Linked Search Ads 360 (SA360)

​Linked Display & Video 360 (DV360)

​Linked Campaign Manager 360 (CM360)

​Page & content

​Event

​Link & file interactions (Enhanced Measurement)

​Ecommerce item

​Device & platform

​App

​Geography

​Audience

​Time

​Time & date grouping

​Custom breakdowns

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Sessions & users

Engagement

Events

Conversions (key events)

Ecommerce revenue

Ecommerce funnel

Advertising (linked accounts)

Organic search (Search Console link)

App stability

Custom metrics

Breakdowns

Traffic source (event-scoped)

Traffic source (session-scoped)

Traffic source (first-user / acquisition)

Manual UTM tagging

Linked Google Ads

Linked Search Ads 360 (SA360)

Linked Display & Video 360 (DV360)

Linked Campaign Manager 360 (CM360)

Page & content

Event

Link & file interactions (Enhanced Measurement)

Ecommerce item

Device & platform

App

Geography

Audience

Time

Time & date grouping

Custom breakdowns

Limitations

API references

See also