> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Data reference
> Metrics, breakdowns, refresh cadence, and limits for the Google Analytics 4 data source in Adriel.
## 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-sources/g-n/google-analytics-4/how-to-connect).
## 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](https://support.google.com/analytics/answer/9333790)).
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 columns**
Code 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 helpers**
The "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 columns**
Code 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 variants**
GA4 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 fallback**
The 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](https://support.google.com/analytics/answer/13331292)).
* **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](https://support.google.com/analytics/answer/13331684)). 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](https://support.google.com/analytics/answer/9383630)).
* **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.
## API references
* [Google Analytics Data API (v1beta)](https://developers.google.com/analytics/devguides/reporting/data/v1)
* [Data API breakdowns & metrics reference](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema)
* [Google Analytics Admin API (v1alpha)](https://developers.google.com/analytics/devguides/config/admin/v1)
* [GA4 property metadata endpoint](https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/getMetadata)
* [Data sampling in GA4](https://support.google.com/analytics/answer/13331292)
* [Cardinality and "(other)" rows](https://support.google.com/analytics/answer/13331684)
## See also
* [How to connect Google Analytics 4](/data-sources/g-n/google-analytics-4/how-to-connect) (paired how-to)
* [Google Ads data reference](/data-sources/g-n/google-ads/data-reference) — for the paid-media counterpart
* [Google Search Console data reference](/data-sources/g-n/google-search-console/data-reference) — for organic search performance
* [Piano Analytics data reference](/data-sources/o-z/piano-analytics/data-reference) — for the alternative analytics connector