Google Ads Integration: The Complete Reference

What Data Blueprint Syncs from Google

Google Ads is Blueprint's most comprehensive integration, covering six distinct data categories that feed into nearly every feature in the platform. At the campaign level, Blueprint pulls campaign names, statuses, types, budgets, daily spend totals, and impression share metrics. These campaign-level data points power the Budget Pacing dashboard, where MTD spend is tracked against your monthly targets, and the Impression Share Erosion detector, which flags campaigns losing visibility over time. Every campaign sync includes both the current day's metrics and a rolling window of historical data so that trend lines remain unbroken even if a single sync is delayed.

At the keyword level, Blueprint syncs keyword text, match types, statuses, bids, and -- critically -- Quality Scores with all three sub-components: expected click-through rate, ad relevance, and landing page experience. These Quality Score data points are stored as snapshots in TimescaleDB hypertables, giving you a longitudinal view of how keyword quality evolves over weeks and months. Most PPC tools show you a single point-in-time Quality Score; Blueprint shows you the trajectory, so you can correlate score changes with specific optimizations you made.

Search terms are pulled with full daily granularity over a 30-day rolling window. Each search term record includes the query text, the keyword it matched to, impressions, clicks, cost, and conversions. Blueprint feeds this data into its n-gram analysis engine, which breaks queries into unigrams, bigrams, and trigrams to surface patterns that individual search term reviews would miss. Change history captures every modification made to the account -- bid changes, budget adjustments, status updates, ad copy edits -- along with who made the change and when. This feeds directly into Blueprint's Change Impact detector, which compares performance in a 7-day window before and after each change. Finally, conversion actions are synced so Blueprint can attribute conversion data accurately across campaigns and keywords.

Account Discovery and Connection

When you click Connect Google Ads from your Blueprint workspace, you are taken through Google's standard OAuth 2.0 consent flow. You sign in with the Google account that has access to your ad accounts and approve the requested permissions. Blueprint requests offline access, which means Google issues both an access token for immediate API calls and a refresh token for long-term access. The refresh token allows Blueprint to continue pulling data indefinitely without requiring you to re-authorize -- unlike Meta, where tokens expire after 60 days.

After authorization, Blueprint calls the CustomerService.listAccessibleCustomers endpoint to discover every Google Ads account your login can reach. This includes accounts nested under MCC (Manager) hierarchies, which is how most agencies organize their client accounts. For each customer ID returned, Blueprint makes a subsequent getCustomerDetails call to retrieve the account name, status, and type. Manager accounts (MCCs) are automatically filtered out because they do not contain campaign data -- they only serve as organizational containers. Blueprint also identifies and excludes Local Services Ads accounts, which use a fundamentally different API surface and data model that is not compatible with Blueprint's campaign-level analytics.

The remaining accounts -- individual Google Ads accounts with actual campaign data -- are presented to you in a selection list. You check the accounts you want to track, confirm the selection, and Blueprint immediately begins the initial data sync. Each connected account is stored as a workspace-scoped connection, meaning every team member in your workspace can see and work with the data without needing to authorize separately. Only workspace Owners and Managers have permission to add or remove connections.

Sync Schedules

Blueprint uses a system of seven dedicated BullMQ workers to keep your Google Ads data current. Each worker runs on its own schedule and is responsible for a specific data type. Campaign data syncs every 6 hours, pulling campaign names, statuses, types, budgets, and performance metrics. When the campaign sync completes, it chains into dependent workers -- ad group syncs and daily spend record updates -- so that downstream data stays consistent with the latest campaign state. This chaining pattern ensures you never see a situation where campaign-level data is fresh but ad group data is stale.

Keyword data syncs on a 3-day cadence, which balances freshness against API quota consumption. Each keyword sync also triggers Quality Score snapshot creation, capturing the overall QS and all three sub-components for every keyword in the account. These snapshots are stored in TimescaleDB hypertables with automatic partitioning, so even accounts with tens of thousands of keywords maintain fast query performance over months of historical data. Daily spend records sync every 6 hours using a LAST_7_DAYS date range, which provides overlap to catch any late-arriving data from Google's reporting pipeline.

Search term data syncs every 7 days because search term reports are significantly heavier API calls. Each sync pulls 30 days of data at daily granularity, giving Blueprint's n-gram engine a full month of query volume to analyze. Change history syncs every 6 hours using a delta approach -- it only pulls changes since the last successful sync, not the full history every time. This keeps the change history current for the Change Impact detector without wasting API quota on data you have already ingested. Conversion actions also sync every 6 hours, ensuring that attribution data stays aligned with campaign and keyword metrics.

Google-Specific Features

Quality Score tracking is one of Blueprint's most distinctive capabilities, and it is only available for Google Ads and Microsoft Ads accounts. For Google Ads, Blueprint captures the overall Quality Score (1--10) along with its three component ratings: expected click-through rate, ad relevance, and landing page experience. Each component is rated as "Below Average," "Average," or "Above Average." Blueprint takes a snapshot of these values approximately every 3 days and stores them in TimescaleDB hypertables, creating a historical trend line that you can view on the Quality Scores dashboard. This lets you see not just where a keyword's quality stands today, but how it has changed over time and whether recent optimizations are moving the needle.

Search term analysis goes beyond simply listing the queries that triggered your ads. Blueprint's n-gram engine breaks every search term into its component words and phrases, then aggregates performance metrics at the n-gram level. This means you can see that the bigram "cheap flights" appeared in 47 different search terms and collectively drove 2,300 clicks at a $4.20 CPA -- even if no single search term containing "cheap flights" would have stood out on its own. This n-gram analysis is exclusive to platforms that provide search term data, which means Google Ads and Microsoft Ads but not Meta Ads.

Change history integration powers Blueprint's Change Impact detector. Every time someone modifies a campaign, ad group, keyword, or ad in Google Ads, Google records that change with a timestamp and the identity of the person who made it. Blueprint syncs this change history and then runs a 7-day pre/post performance comparison for each change event. If a bid increase on a keyword led to a 30% cost increase with only a 5% conversion increase, the Change Impact detector surfaces that correlation automatically. Impression share data, which is unique to Google and Microsoft, feeds the Impression Share Erosion detector. This detector watches for campaigns where your impression share is declining over time and alerts you before the erosion becomes significant enough to impact your results.

Technical Details for Advanced Users

Blueprint queries the Google Ads API using GAQL (Google Ads Query Language), a SQL-like syntax that allows precise control over which fields and date ranges are requested. Each query is executed through the paginated search method rather than searchStream. While searchStream is Google's recommended approach for large result sets, it has a hard cap of 10,000 rows per stream, which is insufficient for accounts with extensive keyword or search term data. The paginated search method uses page tokens to iterate through the full result set regardless of size, ensuring Blueprint captures every row even in the largest accounts.

One important technical detail: Google Ads API returns cost values in micros -- that is, the cost in the account's currency multiplied by 1,000,000. A cost of $45.67 is returned as 45670000. Blueprint divides by 1,000,000 during ingestion and stores normalized values in the database. This is the opposite of Microsoft Ads, which returns cost in dollars and requires multiplication to normalize. If you are comparing raw API data against what Blueprint displays, keep this conversion factor in mind. Additionally, several numeric fields in the Google Ads API are returned as strings rather than numbers. Blueprint applies Number() parsing during ingestion to ensure all metrics are stored as proper numeric types for aggregation and comparison.

Rate limiting is handled transparently by Blueprint's BullMQ workers. Each worker respects Google's daily quota limits and per-request rate limits, backing off automatically when throttled. The workers are configured with concurrency limits so that multiple accounts syncing simultaneously never collectively exceed your Google Ads API quota. If a sync job fails due to a transient API error, it is automatically retried with exponential backoff up to three times before being marked as failed and surfaced in the connection status UI.

Troubleshooting Common Issues

The most common issue with Google Ads connections is token refresh failure. While Google refresh tokens are technically long-lived, they can be invalidated if you change your Google account password, revoke Blueprint's access from your Google account security settings, or if your Google account is suspended. When a refresh token fails, Blueprint marks the connection as ERROR and stops attempting syncs. To resolve this, navigate to Settings → Connections, click Reconnect on the affected connection, and complete the OAuth flow again. Blueprint will issue a new refresh token and resume syncing from where it left off -- no historical data is lost.

Sync failures can also occur when Google Ads API quotas are exhausted. This is more likely if you have many accounts connected or if the accounts are very large. Blueprint's worker queue automatically pauses and retries when quota errors are detected, but if the issue persists across multiple retry cycles, the connection will show an ERROR state. In most cases, waiting until the next day (when Google resets daily quotas) resolves the problem automatically. If you consistently hit quota limits, contact Blueprint support to discuss optimizing your sync configuration.

Missing data is occasionally reported when users expect to see metrics that Google Ads does not provide for certain campaign types. For example, Local Services Ads (LSA) campaigns use a fundamentally different data model and are excluded from Blueprint's sync process entirely. If you notice an account has fewer campaigns in Blueprint than in the Google Ads UI, check whether the missing campaigns are LSA campaigns. Similarly, some campaign types like Performance Max have limited keyword-level data in the Google Ads API, which means Quality Score tracking is not available for those campaigns. Blueprint displays whatever data the API provides and does not fabricate metrics for unsupported campaign types.