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

One scope today: https://www.googleapis.com/auth/adwords. Features that need more will ask separately, at the point you turn them on, rather than widening this one. 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 data: not synced. Google's API returns Auction Insights only to allowlisted accounts, so competitor targeting works from the names you enter.
  • 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)
  • 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. For each manager the login opens, it also reads the manager's client accounts (enabled, not hidden, up to 200) and records which manager reaches each one. The Google Ads API requires the login-customer-id header on every request through an MCC.

Resolution priority:

  1. If the account was found under a manager: send that manager's ID.
  2. If stored grant type is mcc: always send the stored MCC ID.
  3. If stored as direct: heuristic fallback viagoogle_ads_accounts table.
  4. On API call failure without MCC header: retry with header, self-heal the stored grant type on success.

Quota handling

Google limits how many API operations VibeAds can make each day, and every VibeAds customer shares that limit. Since September 2026 the limit belongs to VibeAds' Google Cloud project rather than a developer token. VibeAds has Basic access, 15,000 operations a 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

If VibeAds' daily quota runs out, an alternative publish path generates a paste-able Google Ads Script. It runs inside your own Google Ads account, so it doesn't count against VibeAds' shared API quota. 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.

Next steps
Connect Google Ads→
Walkthrough of the OAuth flow
Conversion tracking→
Where the offline upload uses these scopes