> ## 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 Ads data source in Adriel.
## Introduction
Google Ads is Google's paid advertising platform, spanning Search, Display, YouTube, Shopping, Discovery, Performance Max, App, Local Services, Hotel, and other campaign types. Advertisers run paid campaigns through Google Ads Manager, and the connector imports the resulting architecture and performance data via the Google Ads API (GAQL, v23).
As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration.
To connect this data source, see [How to connect Google Ads to Adriel](/data-sources/g-n/google-ads/how-to-connect).
## Data refresh strategy
### Architecture data
Architecture covers ad accounts, campaigns, ad sets (ad groups), ads, and keywords. It refreshes **every 4 hours, on the hour (UTC)**. Only campaigns created within the last **3 years** are imported when the data source is first connected; campaigns created before that window are not back-filled.
### Reports data
Reports include daily performance for ad accounts, campaigns, ad sets, ads, and keywords.
**Real-time.** Report data is fetched from Google on demand when a dashboard loads, so the latest values are always visible. On top of that, scheduled cache refreshes keep historical data consistent across multiple time windows.
**Refresh schedule.** Reports refresh on three overlapping schedules:
* **11:40 PM and 6:40 AM UTC daily** — syncs the last **3 days** for ad account, campaign, ad set, and ad
* **5:00 PM UTC daily** — syncs the last **30 days** for ad account, campaign, ad set, and ad
* **7:30 AM UTC on the 1st and 15th of each month** — syncs the last **90 days** for ad account, campaign, ad set, and ad
## Architecture levels
Ad account → Campaign → Ad set (ad group) → Ad → Keyword → Search term
Performance Max campaigns replace the ad set / ad tier with an **asset group** → **asset** structure.
## Date range limits
| Breakdown | Max range |
| --------- | --------- |
| Daily | 93 days |
| Weekly | 1 year |
| Monthly | 2 years |
## Metrics
**How to read the API Key column**
Code style like `metrics.clicks` is the literal Google Ads API field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field (Adriel-computed rates, cross-connector fallbacks, or aggregated values).
### Reach & impressions
| Metric | Description | Data type | API Key |
| ----------- | ----------------------------------------------------------------- | --------- | ------------------------------------------ |
| Impressions | Total times the ads were displayed, regardless of interaction. | Number | `metrics.impressions` |
| Reach | Unique users who saw the ad at least once. | Number | *Estimated from impressions and frequency* |
| Frequency | Average times each reached user saw the ad (impressions ÷ reach). | Ratio | *Adriel-computed* |
### Click performance
| Metric | Description | Data type | API Key |
| ------------ | ----------------------------------------------------------------------- | ---------- | ----------------- |
| Clicks (all) | Total clicks, including link, social, carousel, and other interactions. | Number | `metrics.clicks` |
| Link clicks | Clicks on the ad's link. | Number | `metrics.clicks` |
| CTR | Click-through rate (clicks ÷ impressions). | Percentage | *Adriel-computed* |
### Cost & spend
| Metric | Description | Data type | API Key |
| ------------------------ | ----------------------------------------------------------------------- | --------- | --------------------------------------------- |
| Ad spend | Total amount spent during the reporting period. | Currency | `metrics.costMicros` *(divided by 1,000,000)* |
| CPM | Cost per thousand impressions. | Currency | `metrics.averageCpm` |
| CPC | Cost per click. | Currency | `metrics.averageCpc` |
| CPA | Cost per conversion (spend ÷ conversions). | Currency | *Adriel-computed* |
| CPR | Cost per result — spend divided by the resolved Result count. | Currency | *Adriel-computed* |
| Cost Per Conversion | Google-reported cost per primary conversion. | Currency | `metrics.costPerConversion` |
| Cost Per All Conversions | Google-reported cost per any recorded conversion (primary + secondary). | Currency | `metrics.costPerAllConversions` |
**Currency conversion**
Each ad account's currency comes from its Google Ads settings. When an ad account's currency differs from the workspace currency, costs are automatically converted using the current day's exchange rate.
### Engagement
| Metric | Description | Data type | API Key |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------ |
| Engagement | Any user interaction with the ad — clicks, reactions, shares, etc. | Number | `metrics.engagements` |
| Engagement Rate | Engagements as a share of impressions. | Percentage | `metrics.engagementRate` |
| Post engagement / reactions / comments / shares / saves | Included for cross-connector consistency; Google Ads does not natively track post-style engagement, so these surface zero for Google campaigns. | Number | *Not natively tracked by Google Ads* |
### Video performance
| Metric | Description | Data type | API Key |
| ---------------------------------------------- | -------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------ |
| Video impressions | Times video creatives started displaying. | Number | `metrics.impressions` *(filtered to video campaigns)* |
| Video play | Any play of the video, regardless of duration. | Number | *Aggregated from video engagement events* |
| Views | Aggregated count of qualified video views. | Number | `metrics.engagements` |
| 2s / 3s / 6s / 15s / 30s video plays | Plays lasting at least the given number of continuous seconds. | Number | *Aggregated internally* |
| Thru plays | Video viewed to ≥97% or 15 seconds, whichever comes first. | Number | *Aggregated internally* |
| Video played to 25% / 50% / 75% / 100% (Views) | Plays reaching each completion threshold. | Number | `metrics.videoQuartileP25Rate` / `_P50_` / `_P75_` / `_P100_` *(rate × impressions)* |
| Video played to 25% / 50% / 75% / 100% (%) | Each quartile as a rate over video impressions. | Percentage | *Adriel-computed* |
| View rate | Video views ÷ video impressions. | Percentage | *Adriel-computed* |
| CPV | Cost per video view (spend ÷ views). | Currency | *Adriel-computed* |
| Average CPV | Google-reported average cost per view. | Currency | `metrics.averageCpv` |
| Average CPE | Google-reported average cost per engagement. | Currency | `metrics.averageCpe` |
**Video metrics at the ad-account level**
Google's API does not allow video quartile metrics to be queried at the ad-account level. When a video metric is requested at account level, the query is automatically promoted to campaign level and results are aggregated.
### Conversion performance
| Metric | Description | Data type | API Key |
| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------- |
| Conversions | Attributed actions matching the defined **primary** conversion events. Defaults to "Purchase" when no specific event is set. | Number | `metrics.conversions` |
| All conversions (Google) | Count of every conversion action recorded — primary plus secondary goals. | Number | `metrics.allConversions` |
| Conversion value | Monetary value of attributed conversions. | Currency | `metrics.conversionsValue` |
| All conversions value | Monetary value of all conversions (primary + secondary). | Currency | `metrics.allConversionsValue` |
| Revenue | Alias for conversion value — monetary value of attributed conversions. | Currency | `metrics.conversionsValue` |
| ROAS | Return on ad spend (conversion value ÷ spend). | Ratio | *Adriel-computed* |
| CVR | Conversion rate (conversions ÷ clicks × 100%). | Percentage | *Adriel-computed* |
| Conversions From Interactions Rate | Google-reported conversion rate over interactions. | Percentage | `metrics.conversionsFromInteractionsRate` |
| All Conversions From Interactions Rate | Google-reported all-conversions rate over interactions. | Percentage | `metrics.allConversionsFromInteractionsRate` |
| Value Per Conversion | Average value per primary conversion. | Currency | `metrics.valuePerConversion` |
| Value Per All Conversions | Average value per any conversion. | Currency | `metrics.valuePerAllConversions` |
| Conversions Value Per Cost | Conversion value divided by cost. | Ratio | `metrics.conversionsValuePerCost` |
| All Conversions Value Per Cost | All-conversions value divided by cost. | Ratio | `metrics.allConversionsValuePerCost` |
| Conversions By Conversion Date | Conversions counted by the date the conversion occurred (not the click date). | Number | `metrics.conversionsByConversionDate` |
| All Conversions By Conversion Date | All conversions counted by the conversion date. | Number | `metrics.allConversionsByConversionDate` |
| Conversions Value By Conversion Date | Conversion value counted by the conversion date. | Currency | `metrics.conversionsValueByConversionDate` |
| All Conversions Value By Conversion Date | All-conversions value counted by the conversion date. | Currency | `metrics.allConversionsValueByConversionDate` |
| Interactions | Total user interactions with the ad (Google's superset of clicks). | Number | `metrics.interactions` |
| Interaction Rate | Interactions as a share of impressions. | Percentage | `metrics.interactionRate` |
| Interaction Event Types | Array of interaction event types recorded. | Array | `metrics.interactionEventTypes` |
| Orders | Shopping / commerce order count. | Number | `metrics.orders` |
| View Through Conversions | Conversions attributed to ad views (no click). | Number | `metrics.viewThroughConversions` |
**Conversions vs. All conversions**
"Conversions" reflects only conversion actions flagged as **primary** in the Google Ads setup. "All conversions" includes every conversion action, primary or secondary. Two different numbers appearing in different widgets usually means each is using a different one of these.
### Custom conversion events
Each conversion action configured in the Google Ads account is automatically imported. For every imported event, these metrics are auto-generated:
| Pattern | Description | Data type | API Key |
| -------------------------------------------- | ---------------------------------------- | ---------- | ------------------------------------------------------ |
| `Google Ads: [event_name]` | Count of that event. | Number | *Resolved from the event name in the Google Ads setup* |
| `Google Ads: [event_name]: Conversion value` | Monetary value attributed to that event. | Currency | *Resolved* |
| `Google Ads: [event_name]: CPA` | Cost per action (spend ÷ count). | Currency | *Adriel-computed* |
| `Google Ads: [event_name]: ROAS` | Return on ad spend (value ÷ spend). | Ratio | *Adriel-computed* |
| `Google Ads: [event_name]: CVR` | Conversion rate (count ÷ clicks × 100%). | Percentage | *Adriel-computed* |
Custom event metrics only appear in dashboards when the underlying event is active in the Google Ads account.
Account-level KPI variants also exist for the standard reporting categories: `Conversions: ROAS / CPA / CVR`, `Conversions (All Conv): ROAS / CPA / CVR`, `Interactions: CPA / CVR`, `Orders: CPA / CVR`, `View Through Conversions: CPA / CVR`.
### Auction insights
| Metric | Description | Data type | API Key |
| ------------------------------------------------ | --------------------------------------------------------------- | ---------- | ---------------------------------------------------- |
| Search Impression Share | Share of eligible impressions actually received on Search. | Percentage | `metrics.searchImpressionShare` |
| Search Top Impression Share | Share of top-of-page impressions received on Search. | Percentage | `metrics.searchTopImpressionShare` |
| Search Absolute Top Impression Share | Share of absolute-top impressions received on Search. | Percentage | `metrics.searchAbsoluteTopImpressionShare` |
| Search Budget Lost Impression Share | Search impressions lost to budget. | Percentage | `metrics.searchBudgetLostImpressionShare` |
| Search Budget Lost Top Impression Share | Search top impressions lost to budget. | Percentage | `metrics.searchBudgetLostTopImpressionShare` |
| Search Budget Lost Absolute Top Impression Share | Search absolute-top impressions lost to budget. | Percentage | `metrics.searchBudgetLostAbsoluteTopImpressionShare` |
| Search Rank Lost Impression Share | Search impressions lost to ad rank. | Percentage | `metrics.searchRankLostImpressionShare` |
| Search Rank Lost Top Impression Share | Search top impressions lost to ad rank. | Percentage | `metrics.searchRankLostTopImpressionShare` |
| Search Rank Lost Absolute Top Impression Share | Search absolute-top impressions lost to ad rank. | Percentage | `metrics.searchRankLostAbsoluteTopImpressionShare` |
| Search Click Share | Clicks received divided by estimated eligible clicks on Search. | Percentage | `metrics.searchClickShare` |
| Search Exact Match Impression Share | Share of exact-match search impressions received. | Percentage | `metrics.searchExactMatchImpressionShare` |
| Content Impression Share | Share of eligible impressions received on Display / Content. | Percentage | `metrics.contentImpressionShare` |
| Content Budget Lost Impression Share | Display impressions lost to budget. | Percentage | `metrics.contentBudgetLostImpressionShare` |
| Content Rank Lost Impression Share | Display impressions lost to ad rank. | Percentage | `metrics.contentRankLostImpressionShare` |
| Top Impression Percentage | Percentage of impressions shown in a top position. | Percentage | `metrics.topImpressionPercentage` |
| Absolute Top Impression Percentage | Percentage of impressions shown in the absolute-top position. | Percentage | `metrics.absoluteTopImpressionPercentage` |
### Cross-device conversions
| Metric | Description | Data type | API Key |
| ------------------------------------- | ---------------------------------------------------------------- | --------- | ------------------------------------------- |
| Cross Device Conversions | Conversions that started on one device and completed on another. | Number | `metrics.crossDeviceConversions` |
| Cross Device Conversions Value Micros | Monetary value of cross-device conversions (in micros). | Currency | `metrics.crossDeviceConversionsValueMicros` |
### Cross-sell & new customer
| Metric | Description | Data type | API Key |
| ------------------------------------ | ------------------------------------------------------------- | --------- | ---------------------------------------- |
| Cross Sell Revenue Micros | Revenue from cross-sell (in micros). | Currency | `metrics.crossSellRevenueMicros` |
| Cross Sell Cost Of Goods Sold Micros | COGS from cross-sell (in micros). | Currency | `metrics.crossSellCostOfGoodsSoldMicros` |
| Cross Sell Gross Profit Micros | Gross profit from cross-sell (in micros). | Currency | `metrics.crossSellGrossProfitMicros` |
| Cross Sell Units Sold | Units sold from cross-sell. | Number | `metrics.crossSellUnitsSold` |
| New Customer Lifetime Value | Projected lifetime value of new customers acquired. | Currency | `metrics.newCustomerLifetimeValue` |
| All New Customer Lifetime Value | Projected lifetime value across all new-customer conversions. | Currency | `metrics.allNewCustomerLifetimeValue` |
| Average Order Value Micros | Average order value (in micros). | Currency | `metrics.averageOrderValueMicros` |
| Average Cart Size | Average number of items per order. | Number | `metrics.averageCartSize` |
### Active View (viewability)
| Metric | Description | Data type | API Key |
| ------------------------------------ | ------------------------------------------------------- | ---------- | ----------------------------------------- |
| Active View Impressions | Impressions that met Active View's viewable definition. | Number | `metrics.activeViewImpressions` |
| Active View Measurable Impressions | Impressions eligible for Active View measurement. | Number | `metrics.activeViewMeasurableImpressions` |
| Active View Measurable Cost (Micros) | Cost of measurable impressions (in micros). | Currency | `metrics.activeViewMeasurableCostMicros` |
| Active View Measurability | Share of impressions that were measurable. | Percentage | `metrics.activeViewMeasurability` |
| Active View Viewability | Share of measurable impressions that were viewable. | Percentage | `metrics.activeViewViewability` |
| Active View CPM | Average cost per thousand viewable impressions. | Currency | `metrics.activeViewCpm` |
### Phone & call conversions
| Metric | Description | Data type | API Key |
| ------------------ | ----------------------------------------- | ---------- | -------------------------- |
| Phone Calls | Calls placed from call extensions. | Number | `metrics.phoneCalls` |
| Phone Impressions | Impressions of call extensions. | Number | `metrics.phoneImpressions` |
| Phone Through Rate | Phone calls divided by phone impressions. | Percentage | `metrics.phoneThroughRate` |
### Location asset conversions
| Metric | Description | Data type | API Key |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------------------------------------------- |
| All Conversions From Click To Call | Conversions from click-to-call actions. | Number | `metrics.allConversionsFromClickToCall` |
| All Conversions From Directions | Conversions from directions requests. | Number | `metrics.allConversionsFromDirections` |
| All Conversions From Menu | Conversions from menu views. | Number | `metrics.allConversionsFromMenu` |
| All Conversions From Order | Conversions from order actions. | Number | `metrics.allConversionsFromOrder` |
| All Conversions From Other Engagement | Conversions from other engagement actions. | Number | `metrics.allConversionsFromOtherEngagement` |
| All Conversions From Store Visit | Conversions from store visits. | Number | `metrics.allConversionsFromStoreVisit` |
| All Conversions From Store Website | Conversions from store-website actions. | Number | `metrics.allConversionsFromStoreWebsite` |
| All Conversions From Location Asset \[action] | Same as above, restricted to location-asset attribution. Available for click-to-call, directions, menu, order, other engagement, store visits, and website. | Number | `metrics.allConversionsFromLocationAsset*` |
| View Through Conversions From Location Asset \[action] | View-through variant of the above. | Number | `metrics.viewThroughConversionsFromLocationAsset*` |
### Cost & revenue (raw micros)
| Metric | Description | Data type | API Key |
| ------------------------- | ------------------------------------------------------------------------------- | ---------- | ------------------------------- |
| Cost Micros | Raw cost value from Google, in micros. Divide by 1,000,000 for currency amount. | Number | `metrics.costMicros` |
| Revenue Micros | Raw revenue value from Google, in micros. | Number | `metrics.revenueMicros` |
| Cost Of Goods Sold Micros | Raw COGS from Google, in micros. | Number | `metrics.costOfGoodsSoldMicros` |
| Gross Profit Micros | Raw gross profit from Google, in micros. | Number | `metrics.grossProfitMicros` |
| Gross Profit Margin | Gross profit divided by revenue. | Percentage | `metrics.grossProfitMargin` |
| Average Cost | Google-reported average cost. | Currency | `metrics.averageCost` |
### Budget & schedule
| Metric | Description | Data type | API Key |
| --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------- |
| Daily budget | Daily budget set on the campaign or ad set. | Currency | `budget.amountMicros` *when* `budget.period = DAILY` |
| Lifetime budget | Total budget allocated for the campaign's lifetime. | Currency | `budget.amountMicros` *when* `budget.period ≠ DAILY` |
| Bid cap | Bid cap set on the ad set or campaign. | Currency | `adGroup.cpcBidMicros` |
| Starts | Campaign start date. | Date | `campaign.startDate` |
| Ends | Campaign end date. | Date | `campaign.endDate` |
| Days remaining | Days between today and campaign end. | Number | *Adriel-computed (campaign.endDate − today)* |
### UTM tracking
| Metric | Description | Data type | API Key |
| ------------ | -------------------------------- | --------- | ---------------------------------------------- |
| UTM Source | Parsed `utm_source` parameter. | Text | *Adriel-parsed from ad config and landing URL* |
| UTM Medium | Parsed `utm_medium` parameter. | Text | *Adriel-parsed* |
| UTM Campaign | Parsed `utm_campaign` parameter. | Text | *Adriel-parsed* |
| UTM Content | Parsed `utm_content` parameter. | Text | *Adriel-parsed* |
| UTM Term | Parsed `utm_term` parameter. | Text | *Adriel-parsed* |
### Campaign structure metadata
| Metric | Description | Data type | API Key |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------- |
| Ad account name | Name of the ad account. | Text | `customer.descriptiveName` |
| Ad account ID | Google-side customer identifier. | Text | `customer.id` |
| Campaign name | Campaign name. | Text | `campaign.name` |
| Campaign ID | Google-side campaign identifier. | Text | `campaign.id` |
| Ad set name | Ad set (ad group) name. | Text | `adGroup.name` |
| Ad set ID | Google-side ad group identifier. | Text | `adGroup.id` |
| Ad name | Ad name. | Text | `adGroupAd.ad.name` (or `creative.params.titles`) |
| Ad ID | Google-side ad identifier. | Text | `adGroupAd.ad.id` |
| Keyword name | Keyword text (Search campaigns only). | Text | `adGroupCriterion.keyword.text` |
| Status | Campaign / ad set / ad status. | Text | `campaign.status`, `adGroup.status`, `adGroupAd.status` |
| Channel | Campaign type — Search, Display, YouTube, Performance Max, Discovery, Shopping, Local, Hotel, and so on. | Text | `campaign.advertisingChannelType`, `advertisingChannelSubType`, `appCampaignSetting.appStore` |
| Channel ID | Internal channel identifier at each hierarchy level. | Text | `customer.id`, `campaign.id`, `adGroup.id`, `adGroupAd.ad.id` |
| Bid Strategy | Bid strategy set on the ad set or campaign. | Text | `campaign.biddingStrategyType` |
| Objective | Campaign objective — mapped from Google's bidding strategy (LINK\_CLICKS, APP\_INSTALLS, CONVERSIONS, REACH, WATCH\_VIDEO). | Text | `campaign.biddingStrategyType` |
| Currency | Ad account currency. | Text | `customer.currencyCode` |
| Creative type | Type of the ad creative (e.g. image, video, responsiveSearchAd). | Text | `adGroupAd.ad.type` |
| Creative URL | Destination URL of the ad. | URL | `adGroupAd.ad.displayUrl`, `adGroupAd.ad.finalUrls` |
| Creative image | Ad creative image; visually similar images are auto-clustered. | URL | *Resolved from creative asset URLs* |
| Asset group | Performance Max asset group. | Text | `assetGroupAsset.performanceLabel` |
### AI creative analysis
| Metric | Description | Data type | API Key |
| -------------------------- | -------------------------------------------------------- | --------- | ------------------------------------- |
| AI aggregated text content | Adriel-derived text summary of the creative's copy. | Text | *Adriel-derived from creative assets* |
| AI primary subject | Adriel-derived primary subject detected in the creative. | Text | *Adriel-derived* |
| AI dominant font | Adriel-detected dominant font used in the creative. | Text | *Adriel-derived* |
| AI product presence | Whether a product is detected in the creative. | Boolean | *Adriel-derived* |
### Result Indicator mapping
The "Result Indicator" metric reflects the action a campaign is optimized for. It's resolved in this order:
1. If a campaign has a **conversion goal** (for example app installs, content views), the conversion goal is used.
2. Otherwise, the campaign **marketing objective** maps to a default indicator:
| Marketing objective | Default Result Indicator |
| ---------------------------------------------------------------------------------- | ---------------------------- |
| `APP_INSTALLS`, `MOBILE_APP_INSTALL` | `appInstall` |
| `CONVERSIONS`, `EVENT_RESPONSES`, `JOB_APPLICANT`, `OFFER_CLAIMS`, `OUTCOME_SALES` | Derived from conversion goal |
| `BRAND_AWARENESS`, `REACH` | `reach` |
| `VIDEO_VIEWS` | `videoViews` |
| `CREATIVE_ENGAGEMENT`, `ENGAGEMENT`, `POST_ENGAGEMENT` | `engagements` |
| `LEAD_GENERATION` | `lead` |
| `MESSAGES` | `messages` |
| `PLACE` | `impressions` |
1. If neither applies, **`clicks`** is used as the default.
## Breakdowns
### Standard hierarchy
| Breakdown | Description | API Key |
| ----------- | -------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Channel | Constant grouping label — for Google Ads this is always "google". Used for cross-connector rollup. | *Constant value* |
| Ad account | Group by ad account. | `customer.id` |
| Campaign | Group by campaign. | `campaign.id` |
| Ad set | Group by ad set / ad group. | `adGroup.id` |
| Ad | Group by ad. | `adGroupAd.ad.id` |
| Keyword | Group by keyword (Search campaigns only). | `adGroupCriterion.keyword.text` |
| Search term | Group by the actual user search query (Search campaigns only). | *Resolved from search term match data* |
| Asset group | Performance Max asset group. | `assetGroupAsset.performanceLabel` |
### Demographics
| Breakdown | Description | API Key |
| --------- | --------------------- | ------------------------------------------ |
| Age | Audience age bracket. | *Resolved from Google's audience segments* |
| Gender | Audience gender. | *Resolved from Google's audience segments* |
### Geographic
| Breakdown | Description | API Key |
| -------------- | --------------------------------------------- | ------------------------------------------------ |
| Location | Cities or regions where impressions occurred. | *Resolved from Google's location segments* |
| Store location | Physical store location, when available. | *Resolved from Google's location asset segments* |
### Time & device
| Breakdown | Description | API Key |
| ----------- | ------------------------------ | -------------------------------------------- |
| Hour of day | 1-hour blocks across the day. | *Resolved from Google's segment aggregation* |
| Month | Month of the reporting period. | *Resolved from Google's segment aggregation* |
### Creative content
| Breakdown | Description | API Key |
| -------------------- | ----------------------------------- | ------------------------------------------ |
| Creative headline | Group by creative headline. | `adGroupAd.ad.[AD_TYPE].headlines.text` |
| Creative description | Group by creative description text. | `adGroupAd.ad.[AD_TYPE].descriptions.text` |
| Ad label | Group by labels assigned to ads. | *Resolved from ad-level label assignments* |
### Performance Max
| Breakdown | Description | API Key |
| ------------------ | ----------------------------------------------- | ---------------------------------- |
| Asset group signal | Performance Max asset group performance signal. | `assetGroupAsset.performanceLabel` |
### Overview & status
| Breakdown | Description | API Key |
| ------------------- | ------------------------------------------------------------- | ------------------------------------------------------------- |
| Bid strategy | Group by bid strategy. | `campaign.biddingStrategyType` |
| Objective | Group by campaign objective. | `campaign.biddingStrategyType` |
| Currency | Group by ad account currency. | `customer.currencyCode` |
| Channel ID | Group by internal channel identifier at each hierarchy level. | `customer.id`, `campaign.id`, `adGroup.id`, `adGroupAd.ad.id` |
| Ad account timezone | Group by the ad account's configured time zone. | `customer.timeZone` |
### Time & date grouping
Google's API returns daily records; Adriel groups them into these views for reporting. All time-grouping breakdowns are Adriel-side aggregations of the same underlying daily data.
| 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. |
### Creative analysis
Adriel post-processes ad creatives to generate these breakdowns.
| Breakdown | Description |
| -------------- | ----------------------------------------------- |
| Creative image | Auto-clusters visually similar creative images. |
### UTM tracking
UTM values are parsed by Adriel, not returned by Google. Adriel reads the UTM query parameters from each ad's configuration and landing URL and exposes them as both metrics (for rollup) and breakdowns (for grouping).
| Breakdown | Description |
| ------------ | ------------------------------- |
| UTM Source | Group by parsed `utm_source`. |
| UTM Medium | Group by parsed `utm_medium`. |
| UTM Campaign | Group by parsed `utm_campaign`. |
| UTM Content | Group by parsed `utm_content`. |
| UTM Term | Group by parsed `utm_term`. |
## Limitations
Based on the current connector, Google Ads has the following limits:
* **Campaign recency filter** — only campaigns created within the last 3 years are imported when the data source is first connected; campaigns created before that window are not back-filled. Because Adriel caches data as it syncs, history accumulates from the connection date onward.
* **Ad-level PMax metrics unavailable** — Performance Max campaigns do not expose metrics at the ad tier; reporting is available at the asset group and asset level ([Google Ads Help — Performance Max asset reporting](https://support.google.com/google-ads/answer/10724817)). Queries targeting ads that belong to PMax campaigns surface a `GOOGLE_PMAX_AD_NO_METRICS` warning ("Metrics are not available for Google PMax campaigns at the ads level (no metrics on assets)."). Query at asset-group or campaign level instead.
* **PMax with multiple breakdowns** — mixing PMax data with more than one breakdown surfaces a `GOOGLE_PMAX_DATA_NOT_AVAILABLE` warning ("Google PMax campaign reports are not supported for this breakdown"). Campaign-level PMax metrics are not affected.
* **Video quartile metrics not available at account level** — auto-promoted to campaign level and aggregated.
* **Search-only breakdowns** — Keyword and Search term breakdowns only return data for Search campaigns.
* **Query truncation** — when a query asks for more data than the connector can return in a single call, results are flagged with a `dataTruncated` warning on the widget. Narrow the date range, reduce the number of breakdowns, or query at a higher level (campaign instead of keyword) to resolve.
* **Google Local Services Ads is a separate connector** — Local Services Ads requires its own connector setup, with a separate refresh schedule and limitations.
## API references
* [Google Ads API reference](https://developers.google.com/google-ads/api/reference)
* [Google Ads Query Language (GAQL) overview](https://developers.google.com/google-ads/api/docs/query/overview)
* [Reporting metrics catalog](https://developers.google.com/google-ads/api/fields/v23/metrics)
* [Reporting segments catalog](https://developers.google.com/google-ads/api/fields/v23/segments)
* [Performance Max resources](https://developers.google.com/google-ads/api/docs/performance-max/overview)
* [OAuth 2.0 for Google APIs](https://developers.google.com/identity/protocols/oauth2)
## See also
* [Google Ads how-to (paired)](/data-sources/g-n/google-ads/how-to-connect) — step-by-step setup guide
* [Google Analytics 4 (GA4) data reference](/data-sources/g-n/google-analytics-4/data-reference)
* [Google Display & Video 360 (DV360) data reference](/data-sources/g-n/google-display-video-360-dv360/data-reference)
* Google Search Ads 360 data reference
* Google Local Services Ads data reference
* Why revenue looks different in GA4 vs Google Ads