Google Ads integration

VibeAds connects to Google Ads via OAuth 2.0 and the REST Google Ads API v23. The connection is the foundation of the product.

OAuth scope

Single scope: https://www.googleapis.com/auth/adwords. Grants read + write access to your Google Ads account. We do not request billing scope.

Sync cadence

• agent-sync (every 6 hours): per-campaign metrics snapshots, search terms, ad performance, geo performance, device performance, schedule performance, impression share, Quality Score components, conversion actions, asset metrics. Roughly 12 GAQL queries per campaign per cycle, cached aggressively.
• Funnel sync (daily 05:30 UTC): funnel_sessions aggregation per landing page, A/B test significance, drop-off per step.
• GA4 sync (daily 05:00 UTC): bounce rate, session duration, engagement rate, page views.
• Competitor sync (weekly): Auction Insights snapshots per campaign. Max only.
• URL health (every 6 hours): PageSpeed Insights mobile audit + HEAD/GET on every landing page URL.

What we write

• Create new campaigns, budgets, ad groups, keywords, RSAs, extensions
• Update bids (campaign budget, keyword bids, ad group bids)
• Add negative keywords (campaign-level + ad-group-level)
• Add bid modifiers (device, geo, ad schedule)
• Update campaign status (pause, enable)
• Update bidding strategy + target CPA + target ROAS
• Create + update conversion actions
• Upload offline conversions (GCLID + value)
• Upload conversion adjustments (retractions)
• Pause keywords, ads, ad groups
• Replace single headlines within RSAs (Phase 44)

What we read

• Campaign, ad group, keyword, RSA, extension settings
• Performance metrics at every level (campaign, ad group, keyword, search term, ad)
• Quality Score components (expected CTR, ad relevance, landing page experience)
• Ad strength (Excellent, Good, Average, Poor)
• Optimization score + Google's recommendations feed
• Search term reports + first-page CPC estimates
• Asset performance labels (LOW, GOOD, BEST)
• Auction Insights (Max only)
• Customer-level: name, currency, timezone, identity verification status, Customer Data Terms acceptance, Enhanced Conversions setup
• Account-level assets (sitelinks, callouts, snippets at ADVERTISER source)

MCC manager accounts

Agencies typically operate through a manager (MCC) account. VibeAds detects MCC during OAuth and stores both the operating customer ID and the MCC ID. The Google Ads API requires the login-customer-id header on every request through an MCC.

Resolution priority:

1. If stored grant type is mcc: always send the stored MCC ID.
2. If stored as direct: heuristic fallback viagoogle_ads_accounts table.
3. On API call failure without MCC header: retry with header, self-heal the stored grant type on success.

Quota handling

Google Ads API enforces a daily mutate operations cap. As of 2026-04-21 VibeAds has Basic Access (15,000 ops/day). Most accounts never hit the cap.

Defensive infrastructure:

• Per-day quota tracker table
• Op count estimator runs at publish time
• FIFO publish queue if quota would be exceeded
• Auto-queue on RESOURCE_EXHAUSTED response
• Queue processor (15-min cron) drains FIFO when quota resets

Script publishing fallback

For accounts on Explorer Access (developer-token limited), an alternative publish path generates a paste-able Google Ads Script. Runs under your account's own quota, not VibeAds' shared developer token. You paste it into Google Ads → Tools → Bulk Actions → Scripts → Run.

Script-published campaigns are detected post-hoc via GAQL match on campaign name suffix, then VibeAds picks up management as if you had published through the API.