> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/ppc/google-ads.md).
# Google Ads
Connect Google Ads campaigns to Google Sheets, BigQuery, or databases. Automate spend, clicks, impressions, and conversion reporting with Coupler.io.
Google Ads is Google's online advertising platform for creating and managing paid search, display, video, and shopping campaigns. By connecting Google Ads to Coupler.io, you can automatically export your advertising data to spreadsheets, BI tools, or databases without manual work.
## Why connect Google Ads to Coupler.io?
* **Automate reporting** — Schedule regular data refreshes so your dashboards and spreadsheets always have the latest campaign performance data.
* **Combine with other sources** — Merge Google Ads data with Google Analytics, Facebook Ads, CRM, or e-commerce data for a full-funnel view of your marketing spend and results.
* **Access 30+ report types** — Go beyond what the Google Ads interface shows. Pull campaign, keyword, ad group, geographic, demographic, and shopping performance reports — plus structural data like campaign budgets and labels.
* **Flexible destinations** — Export to AI tools, Google Sheets, Excel, BigQuery, Looker Studio, or other supported destinations.
## Prerequisites
Before connecting, make sure you have:
* A Google account with access to at least one active **Google Ads account**
* **Standard** or **Admin** access to the ad account you want to pull data from
* A Coupler.io account
## Quick start
{% hint style="success" %}
Start with a **Campaign performance** report for the last 60 days, split by Date. This gives you a daily breakdown of spend, clicks, impressions, conversions, and other key metrics across all your campaigns. Proceed to the Data sets or AI agent to get a quick snapshot and verify everything is connected correctly.
{% endhint %}
## How to connect
Google Ads uses **OAuth authentication** — you sign in with your Google account directly.
{% stepper %}
{% step %}
In Coupler.io, create a new **data flow** and select **Google Ads** as the source.\
Click **Connect** and sign in with your Google account.
{% endstep %}
{% step %}
Grant Coupler.io the requested permissions to access your advertising data.
{% endstep %}
{% step %}
Select the **ad account(s)** you want to pull data from.
{% endstep %}
{% step %}
Choose a **report type** (see the most popular ones below).
{% endstep %}
{% step %}
Set your **date range**.
{% endstep %}
{% step %}
Choose your **destination** and run the import.
{% endstep %}
{% endstepper %}
## Google Ads data overview
Google Ads in Coupler.io gives you access to over 30 report types organized into several categories. Each report type is designed for a different use case — from high-level campaign performance to granular keyword-level or geographic breakdowns.
## Report types
Google Ads report types are grouped into the following categories.
### Frequently used reports
| Report type | What it contains | When to use it |
| --------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Campaign performance** | Spend, clicks, impressions, conversions, and other metrics at the campaign level | Overall campaign analysis, budget tracking, performance dashboards |
| **Keywords performance** | Keyword-level metrics for search campaigns | Analyzing which keywords drive traffic and conversions |
| **Ad group performance** | Performance metrics at the ad group level | Comparing ad groups within campaigns |
| **Ad performance** | Individual ad creative performance | Identifying top-performing ads and creative variations |
| **Asset group performance** | Performance data for asset groups (Performance Max) | Evaluating Performance Max campaign components |
| **Custom GAQL** | Any data available via Google Ads Query Language | Advanced users who need custom report structures |
### Additional reports
| Report type | What it contains |
| ------------------------------------------------------ | -------------------------------------------------------------------- |
| **Account performance** | Account-level aggregate metrics |
| **Ad group audience performance** | Performance by audience segment at the ad group level |
| **Age range performance** | Performance by age demographic |
| **Gender performance** | Performance by gender demographic |
| **Geographic performance** (by country, state, region) | Performance by geographic location at the ad group or campaign level |
| **Campaign audience performance** | Performance by audience segment at the campaign level |
| **Campaign performance by ad network type** | Performance split by Search, Display, YouTube, etc. |
| **Campaign performance with conversion actions** | Campaign data with named conversion actions |
| **Campaign performance with unique user stats** | Campaign data including unique reach metrics |
| **Click performance** | Individual click-level data |
| **Display keyword performance** | Performance for Display network keywords |
| **Display topics performance** | Performance by topic targeting on the Display network |
| **Landing page / Expanded landing page** | Performance by destination URL |
| **Search query performance** | Actual search terms that triggered your ads |
| **Shopping performance** | Product-level performance for Shopping campaigns |
| **Responsive search ad performance** | Performance of responsive search ad combinations |
| **Video campaign performance** | Performance for video (YouTube) campaigns with conversions |
| **User location performance** | Performance by user's physical location |
| **Placement performance** | Performance by website placement on the Display network |
### Structural data (Core Components)
| Report type | What it contains | When to use it |
| ------------- | ---------------------------------------------- | -------------------------------------------- |
| **Accounts** | Account details and settings | Auditing account configuration |
| **Campaigns** | Campaign structure, status, type, and settings | Monitoring campaign setup and status changes |
| **Ad groups** | Ad group structure, status, and settings | Reviewing ad group organization |
| **Ads** | Individual ad details and approval status | Checking ad review status and configuration |
### Campaign settings and other data
| Report type | What it contains |
| ----------------------------- | ---------------------------------------------- |
| **Campaign budgets** | Budget allocation and spending limits |
| **Campaign criterion** | Targeting criteria applied to campaigns |
| **Campaign labels** | Labels assigned to campaigns for organization |
| **Bidding strategies** | Bidding strategy configuration and performance |
| **Labels** | All labels in the account |
| **User interest / User list** | Audience segments and remarketing lists |
## Time period splits
For performance reports, you can split your data by time period:
* **Date** — One row per day (default)
* **Day of week** — Aggregated by day of the week
* **Week** — One row per week
* **Month** — One row per month
* **Quarter** — One row per quarter
* **Year** — One row per year
You can select multiple time period splits at once. Structural reports (Accounts, Campaigns, Ad groups, Ads) and Custom GAQL don't support time period splits.
## Common report combinations
Here are some useful report choices depending on what you're tracking:
* **Campaign ROI tracking** — Campaign performance report, split by Date, to track daily spend, conversions, and cost per conversion
* **Keyword optimization** — Keywords performance report to find high-cost, low-converting keywords to pause or adjust
* **Audience insights** — Age range + Gender performance reports to understand which demographics convert best
* **Geographic targeting** — Geographic performance by country or region to optimize location bid adjustments
* **Search term analysis** — Search query performance report to discover new keyword opportunities and negative keyword candidates
* **Shopping optimization** — Shopping performance report to track product-level ROAS and identify top sellers
* **Landing page analysis** — Landing page report to see which destination URLs drive the best conversion rates
## Use cases by role
* **PPC managers** — Track campaign and keyword performance daily, identify wasted spend, and optimize bids. Use search query reports to discover new keyword opportunities and add negative keywords.
* **Finance teams** — Monitor ad spend across accounts, reconcile advertising costs with budget allocations, and export data to spreadsheets for financial reporting.
* **E-commerce managers** — Analyze Shopping campaign performance at the product level, track ROAS, and correlate ad spend with revenue data from other sources.
* **Business owners** — Get high-level dashboards combining spend, clicks, and conversions across all campaigns without needing to navigate the Google Ads interface.
* **Agencies** — Pull data from multiple client accounts into a single destination for cross-account comparison and consolidated client reporting.
## Key metrics by category
The Campaign performance report (the most commonly used) organizes metrics into these groups:
| Category | Example metrics |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Budget** | Content budget lost IS, Search budget lost absolute top IS, Search budget lost IS, Search budget lost top IS |
| **Clicks** | CTR, Active view CTR, Invalid click rate, Invalid clicks, Relative CTR |
| **Conversions** | Conversions, All conversions, Conversions value, Cross device conversions, View through conversions, Cost per conversion, Conversions by conversion date |
| **Cost** | Amount spend, CPC, CPM, CPV, CPE, Active view CPM, Cost per conversion |
| **Performance** | Impressions, Clicks, Bounce rate, Search impression share, Content impression share, Absolute top impression %, Top impression % |
| **Cross sell / Sales** | Revenue, Cost of goods sold, Gross profit, Units sold, Orders, Average order value |
| **Video** | Video views, Video view rate, Plays at 25/50/75/100% rate |
| **Phone** | Phone calls, Phone impressions, Phone through rate |
{% hint style="info" %}
For the full list of metrics and dimensions per report type, see the [Supported Metrics and Dimensions](https://help.coupler.io/article/598-google-ads-supported-metrics-and-dimensions) article in the Coupler.io Help Center.
{% endhint %}
## Platform-specific notes
* **Data latency** — Google Ads data is typically available within a few hours. However, conversion data may take up to 24 hours to finalize due to attribution processing. For reliable reporting, use yesterday's date as your end date.
* **Conversion attribution** — Google Ads attributes conversions based on the ad interaction date, not the conversion date. This means conversions may appear on earlier dates as attribution completes. Numbers for recent dates may change over time.
* **Account-level access only** — You can only pull data from ad accounts your Google account has access to. Manager (MCC) account access does not automatically grant access to all sub-accounts.
* **Custom GAQL** — For advanced users, the Custom GAQL report type lets you write queries using [Google Ads Query Language](https://developers.google.com/google-ads/api/fields/v18/overview_query_builder). This gives you full flexibility to pull any combination of fields the Google Ads API supports.
* **Deprecated report types** — Placeholder and Placeholder feed item reports are deprecated as Google has replaced Feeds with Assets. These report types are still available but may be removed in a future update.
* **Custom columns not supported** — Custom columns created inside the Google Ads UI are not part of the Google Ads API. They cannot be retrieved in any report type. If you rely on custom columns, recreate the logic using Coupler.io formula columns or in your destination tool.
* **Weekly split = Monday–Sunday** — When you split data by Week, Google Ads always uses Monday as the week start, regardless of the date range you set. This is defined by the Google Ads API.
* **Aggregate vs. named conversions** — The Campaign performance report shows total conversions and conversion values across all conversion actions. To break down by individual conversion action (e.g., purchases, sign-ups, add-to-cart), use the **Campaign performance with conversion actions name** report type instead.
* **Impression Share metrics are not summable** — Search Impression Share, Search Lost IS (Rank), and Search Lost IS (Budget) are daily ratio metrics. Summing or averaging them across dates produces incorrect results. To get accurate aggregated values, calculate eligible impressions first: `Eligible impressions = impressions / search_impression_share`, then re-aggregate.
* **Performance Max campaigns** — PMax campaigns don't have traditional ads or ad groups — they use asset groups. Queries targeting ad-group or ad-level data won't return PMax results. Use the **Asset group performance** or **Campaign performance** report instead.
* **Cost in micros (Custom GAQL)** — When pulling cost data via Custom GAQL, the API returns `cost_micros`. Divide by 1,000,000 to get the actual currency value.
## Google Ads common issues
Here are the most common issues you might run into when working with the Google Ads source in Coupler.io, along with how to fix them.
### Connection issues
OAuth token expired
Google access tokens can expire or be revoked. If your imports start failing, go to the [Sources page](https://app.coupler.io/app/sources) in Coupler.io and reconnect your Google account.
Wrong Google account
If you signed in with a Google account that doesn't have access to your Google Ads account, disconnect and reconnect using the correct account.
Permissions not granted
Make sure you granted the `adwords` permission during the OAuth flow. If you skipped it, disconnect and reconnect your Google account.
Manager account vs. individual account
If you use a Google Ads Manager (MCC) account, make sure the specific sub-accounts you want to access are linked and accessible under your credentials.
### Missing data or accounts
Ad account not showing up
Only **active** ad accounts you have access to are available for selection. If an account is paused, suspended, or you don't have the right access level, it won't appear. Check your access in [Google Ads > Admin > Access and security](https://ads.google.com/).
No data returned (empty report)
Check that the selected ad account has campaigns that ran during the date range you specified. An empty report usually means no ads were active during that period. If a campaign, ad, or keyword had zero performance metrics in the selected period, it won't appear in results — the Google Ads API does not return rows with all-zero metrics.
Missing recent data
Google Ads data is typically available within a few hours, but conversion data may take up to 24 hours to finalize. Avoid relying on today's data for reporting.
Missing conversion data
Conversions are attributed to the click date, not the conversion date. If you're looking at very recent dates, conversions may still be processing. Allow 24–72 hours for complete conversion data.
Shopping performance returns 0 rows
If no Shopping campaigns ran during the selected period, the report will be empty. Double-check your date range. For more control, try a Custom GAQL query targeting `shopping_performance_view`.
Custom columns from Google Ads UI not available
Custom columns created in the Google Ads interface are not supported by the Google Ads API. They cannot be pulled into any report. Recreate the logic using Coupler.io formula columns or in your destination tool.
App Install and Reach metrics missing
These metrics are not available in all report types. For app install metrics, use the **Ad group performance with install conversion** report. Reach metrics have limited availability — check the [Supported Metrics and Dimensions](https://help.coupler.io/article/598-google-ads-supported-metrics-and-dimensions) article for which report types include them.
### Permission errors
"Insufficient permissions" error
Your Google account must have **Standard** or **Admin** access to the ad account. Read-only access may not be sufficient for all report types. Check your access level in [Google Ads > Admin > Access and security](https://ads.google.com/).
Account access revoked
If someone removed your access to an ad account, imports for that account will fail. Contact the account owner to restore access.
MCC sub-account access
{% hint style="warning" %}
Having Manager (MCC) account access doesn't automatically grant data access to all sub-accounts. You need explicit access to each individual ad account.
{% endhint %}
### Data discrepancies
Numbers don't match Google Ads interface
The most common cause is different date ranges or time zones. Verify that your date range in Coupler.io matches what you're looking at in the Google Ads interface. Also check whether you're comparing the same report segmentation (e.g., by campaign vs. by ad group).
Conversion numbers changing over time
Google Ads uses attribution windows, so conversions can be added to past dates as they are recorded. This is expected behavior — recent conversion data will shift over a few days until the attribution window closes.
Metrics differ from Google Analytics
Google Ads and Google Analytics measure things differently. For example, Google Ads counts clicks while GA4 counts sessions. A single click can result in multiple sessions, or a session may come without a click. These tools also use different attribution models.
Search query data is limited
Google Ads only reports search terms that meet minimum privacy thresholds. Low-volume search terms may be grouped under "Other search terms" and not shown individually.
Rows appear duplicated (hidden dimensions)
If you see what looks like duplicate rows for the same campaign, the most likely cause is hidden dimensions splitting the data. The **Campaign performance by ad network type** report adds an "Ad network type" column that creates separate rows for Search, Display, YouTube, etc. Similarly, other report types may include "Interaction event type" as a hidden dimension.
**How to fix:** Switch to the plain **Campaign performance** report if you don't need the ad-network breakdown. If you're already using it, check for hidden columns in the Transformation step — unhide all columns to identify what's creating the split.
Demand Gen campaign spend appears inflated
If you're using the **Campaign performance by ad network type** report for Demand Gen campaigns, spending is split across multiple ad network type rows. Summing them in a dashboard without filtering produces an inflated total.
**How to fix:** Use the plain **Campaign performance** report, which aggregates across all network types. Remove any filters that may have been applied to the source.
Conversion value discrepancy in Data Studio
Conversion values in Data Studio may not match Google Ads because of how data is aggregated. If you pull data split by Date, Data Studio sums daily values — but if the date range or attribution window differs from the Google Ads UI, the totals won't align.
**How to fix:** Ensure the date range in Coupler.io matches the Data Studio filter. Use yesterday's date as the end date to avoid incomplete data. Check that you're comparing the same conversion metric (e.g., "Conversions value" vs. "All conversions value").
PMax campaign conversions missing from GAQL queries
Performance Max campaigns don't have traditional ads or ad groups — they only have asset groups. If your Custom GAQL query targets `ad_group` or `ad_group_ad` resources, PMax data will be excluded.
**How to fix:** Use the **Campaign performance** or **Asset group performance** report for PMax data. For Custom GAQL, query the `campaign` resource instead of `ad_group`.
### Rate limits and API errors
429 "Too many requests" / "Resource has been exhausted"
{% hint style="danger" %}
This error means the Google Ads API quota has been exceeded. It can happen globally (affecting all Coupler.io users) or per-account.
{% endhint %}
The error message typically includes: `429 Resource has been exhausted (e.g. check quota)` and a retry delay (e.g., "Retry in 17997 seconds").
**How to fix:** Wait approximately 4 hours for Google's quota to reset, then re-run the data flow. Stagger your scheduled refreshes if you have multiple data flows pulling from the same account. Coupler.io has implemented improvements to reduce the likelihood of hitting global quota limits.
Import fails with generic quota error
The Google Ads API has request quotas per developer token and per account. If you have multiple data flows pulling from the same ad account simultaneously, some may hit quota limits. Space out your scheduled refreshes by a few minutes.
Large reports timing out
Reports covering very long date ranges (e.g., multiple years) with daily splits can be slow. Try narrowing the date range or using weekly/monthly splits for historical data.
"Google API currently unavailable" error
This is a transient error from the Google Ads API. It usually resolves on its own within a few hours.
**How to fix:** Wait and re-run the data flow. If the error persists for more than 24 hours, contact Coupler.io support.
## Google Ads FAQ
Answers to the most frequently asked questions about using the Google Ads source in Coupler.io.
What report types are available?
Coupler.io supports over 30 Google Ads report types, organized into groups: Frequently Used (Campaign, Keywords, Ad group, Ad, Asset group performance), Reports (geographic, demographic, search query, shopping, video, and more), Core Components (Accounts, Campaigns, Ad groups, Ads), Campaign Settings, and Strategies and Constants.
{% hint style="info" %}
See the [Data Overview](#google-ads-data-overview) for the full list of report types with descriptions.
{% endhint %}
Can I pull data from multiple ad accounts?
Yes. When configuring the source, you can select multiple ad accounts. Keep in mind that each ad account counts as a separate account toward your Coupler.io plan limit.
What date range can I pull?
For performance reports, you set a start and end date using the date picker. There's no hard limit on the date range, but very long ranges with daily splits can be slow. Structural reports (Accounts, Campaigns, etc.) don't have date range settings — they always pull the current state.
What is Custom GAQL?
Custom GAQL lets you write your own queries using [Google Ads Query Language](https://developers.google.com/google-ads/api/fields/v18/overview_query_builder). This gives advanced users full flexibility to pull any combination of fields the Google Ads API supports. Use the Google Ads Query Builder tool to construct your query, then paste it into the Custom GAQL field in Coupler.io.
Why doesn't my data match what I see in Google Ads?
The most common reasons are different date ranges, time zones, or attribution windows. Verify that your date range and segmentation settings in Coupler.io match what you're looking at in the Google Ads interface. Conversion data in particular can shift over time as attribution completes.
{% hint style="info" %}
See [Common Issues](#google-ads-common-issues) for detailed troubleshooting of data discrepancies.
{% endhint %}
Why are my conversion numbers different from Google Analytics?
Google Ads and Google Analytics use different measurement methodologies. Google Ads counts clicks, while GA4 counts sessions. They also use different attribution models. These differences are expected. For consistent reporting, pick one source of truth and use it consistently.
Why is recent conversion data incomplete?
Google Ads attributes conversions to the click date, not the conversion date. Conversions may take 24–72 hours to fully appear. Set your end date to yesterday for the most reliable results, and allow a few days before treating conversion numbers as final.
How does Coupler.io count Google Ads accounts for billing?
Google Ads is a **tenant-based source**. Coupler.io counts each ad account you select in the setup wizard as one account toward your plan limit. It doesn't matter how many report types or data flows you create — what matters is the number of unique ad accounts used per credential.
Can I schedule automatic data refreshes?
Yes. After setting up your data flow, you can configure a refresh schedule (hourly, daily, weekly, etc.) under the data flow settings. Your destination will be updated automatically.
Where can I find Local Services Ads (LSA) performance?
Local Services Ads is just another advertising channel type in Google Ads, not a separate integration. Connect your Google Ads account as usual — LSA campaign data comes through in the same reports (e.g., Campaign performance) alongside your other campaign types.
Why do I see duplicate rows for the same campaign?
This usually happens because a hidden dimension is splitting each campaign into multiple rows. The most common culprits are "Ad network type" (if you're using Campaign performance by ad network type) and "Interaction event type." Switch to the plain **Campaign performance** report, or unhide all columns in the Transformation step to see what's creating the split.
{% hint style="info" %}
See [Common Issues](#google-ads-common-issues) for more details on duplicated rows.
{% endhint %}
How can I see individual conversion actions (purchases, sign-ups, etc.)?
The standard Campaign performance report only shows aggregate conversions. To break down by named conversion action, use the **Campaign performance with conversion actions name** report type. For ad-group-level conversion breakdowns, use **Custom GAQL** with a query targeting the `ad_group` resource and including `segments.conversion_action_name`.
{% hint style="info" %}
For more on Custom GAQL, see the [Data Overview](#google-ads-data-overview) and the [Google Ads Query Builder](https://developers.google.com/google-ads/api/fields/v18/overview_query_builder).
{% endhint %}
Can I pull hourly data from Google Ads?
Hourly segmentation is not available in the built-in report types — the most granular built-in split is Date. However, you can use **Custom GAQL** with `segments.hour` to get hourly breakdowns. Example:
```
SELECT campaign.name, segments.date, segments.hour, metrics.clicks, metrics.impressions, metrics.cost_micros
FROM campaign
WHERE segments.date BETWEEN '2025-02-16' AND '2025-02-22'
```
Remember that `cost_micros` must be divided by 1,000,000 to get the actual currency value.
Can I use dynamic date ranges in Custom GAQL?
GAQL date filters use the `YYYY-MM-DD` format. Enter fixed dates directly in the query:
```
WHERE segments.date BETWEEN '2025-01-01' AND '2025-02-22'
```
Update the dates manually when you need to shift the window, or set up a scheduled data flow with an appropriate fixed range.
Why is my Shopping performance report empty?
If no Shopping campaigns ran during the selected date range, the report returns 0 rows. Verify the date range covers a period when Shopping campaigns were active. For more flexibility, use a Custom GAQL query: `SELECT campaign.name, segments.product_title, metrics.cost_micros FROM shopping_performance_view WHERE segments.date BETWEEN '2025-01-24' AND '2025-02-22'`
Why can't I find my custom columns from Google Ads?
Custom columns created in the Google Ads UI are not supported by the Google Ads API. They won't appear in any Coupler.io report. To replicate them, use Coupler.io formula columns in the Transformation step, or recreate the logic in your destination tool (Looker Studio, Google Sheets, etc.).
What if I need help?
If you can't resolve an issue using this documentation, contact Coupler.io support with your importer ID and a description of the problem. Note that customer support is available on paid plans only.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.coupler.io/sources/category/ppc/google-ads.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.