Pull Google Ads performance data and generate reports. Use when asked about ad campaign performance, keyword costs, quality scores, ROAS, conversion tracking, or ad spend analysis. Trigger phrases: "google ads", "adwords", "campaign performance", "ad spend", "quality score", "CPC report", "ROAS", "a

Google Ads Report Pull campaign, keyword, and conversion data from the Google Ads API. Prerequisites Requires: GOOGLE CLIENT ID and GOOGLE CLIENT SECRET (OAuth) GOOGLE ADS DEVELOPER TOKEN (apply at https://ads.google.com/home/tools/manager accounts/) GOOGLE ADS CUSTOMER ID (the account ID, format: XXX XXX XXXX , passed without dashes) GOOGLE ADS LOGIN CUSTOMER ID (if using a manager account, the manager account ID) Set in .env , .env.local , or ~/.claude/.env.global . Getting an Access Token API Base Google Ads API uses GAQL (Google Ads Query Language) via REST. Headers: 1. Campaign Performance Report Overview of all campaigns with key metrics. Parsing Campaign Data Important: Cost Micros All cost values in Google Ads API are in micros (1/1,000,000 of the currency unit). Divide by 1,000,000 to get the actual amount. 2. Keyword Performance Report See how individual keywords perform. Quality Score Breakdown Quality Score Components: quality score : Overall score (1 10) creative quality score : Ad relevance (BELOW AVERAGE, AVERAGE, ABOVE AVERAGE) post click quality score : Landing page experience search predicted ctr : Expected click through rate 3. Ad Group Performance 4. Search Terms Report See what users actually searched for (vs. your keywords). Use this to: Find new keyword opportunities (high converting search terms) Identify negative keyword candidates (irrelevant terms with spend) Discover match type issues (broad match pulling in junk traffic) 5. Conversion Tracking ROAS Calculation 6. Daily Spend Trend GAQL Date Ranges Use these built in date ranges in GAQL: TODAY , YESTERDAY LAST 7 DAYS , LAST 14 DAYS , LAST 30 DAYS THIS MONTH , LAST MONTH THIS QUARTER , LAST QUARTER Custom: segments.date BETWEEN '2024 01 01' AND '2024 03 31' Workflow: Monthly Google Ads Report When asked for a full ads report: 1. Account Overview : Total spend, impressions, clicks, conversions, ROAS 2. Campaign Performance : All active campaigns ranked by spend 3. Top Keywords : Top 20 keywords by spend with quality scores 4. Search Terms : Top search terms and negative keyword candidates 5. Quality Score Distribution : How many keywords at each QS level 6. Conversion Analysis : Conversions and ROAS by campaign 7. Daily Trend : Spend and conversion trend over the period Report Format Error Handling Error Cause AUTHENTICATION ERROR Invalid or expired access token AUTHORIZATION ERROR Developer token issue or account access REQUEST ERROR GAQL syntax error QUOTA ERROR API quota exceeded Common GAQL Mistakes Missing WHERE segments.date DURING ... (required for most metric queries) Using REMOVED status filter incorrectly Forgetting to handle costMicros division by 1,000,000 Requesting incompatible resource + segment combinations Tips Always filter out REMOVED campaigns/ad groups/keywords Use searchStream instead of search for large result sets (no pagination needed) Cache results when building multi section reports Quality Score of 0 means "not enough data" treat as null

google-ads-report