{"id":"644f4492-4480-46eb-9f09-7fc0dfb53814","shortId":"YG7nCV","kind":"skill","title":"gaql-reference","tagline":"Google Ads Query Language (GAQL) Reference — complete syntax, resource types, fields, operators, date macros, and ready-to-use query patterns","description":"# Google Ads Query Language (GAQL) Reference\n\nComplete reference for GAQL syntax, resource types, fields, operators, date macros, and common query patterns for Google Ads reporting and optimization.\n\nFull docs: https://cogny.com/docs/gaql-reference\n\n## Usage\n\n```\n/gaql-reference                           # Show full syntax overview\n/gaql-reference search terms              # Search terms report pattern\n/gaql-reference quality score             # Quality Score analysis query\n/gaql-reference impression share          # Budget & impression share query\n/gaql-reference geographic                # Geographic performance query\n/gaql-reference change history            # Change history audit query\n```\n\n## Instructions\n\nYou are a Google Ads Query Language (GAQL) expert. Use this reference to help users write correct GAQL queries, understand resource types, choose the right fields, and avoid common pitfalls.\n\nWhen the user asks a question, find the relevant section below and provide precise, actionable answers with ready-to-use GAQL examples.\n\nIf the user provides a specific topic as an argument, focus on that area. Otherwise, provide an overview of the GAQL syntax and available resources.\n\nWhen the user has Cogny MCP tools available, prefer using `mcp__cogny__google_ads__tool_execute_gaql` to run queries directly and `mcp__cogny__google_ads__tool_get_gaql_doc` or `mcp__cogny__google_ads__tool_get_reporting_view_doc` for API documentation lookups.\n\n---\n\n## Syntax\n\n### Formal Grammar\n\n```\nquery         = SELECT field_list FROM resource_name\n                [ WHERE condition_list ]\n                [ ORDER BY field_name [ ASC | DESC ] ]\n                [ LIMIT positive_integer ]\n                [ PARAMETERS param_list ]\n\nfield_list    = field_name { , field_name }\ncondition_list = condition { AND condition }\ncondition     = field_name operator value\nparam_list    = param_name = param_value { , param_name = param_value }\n```\n\n### Clauses\n\n| Clause | Required | Description |\n|--------|----------|-------------|\n| `SELECT` | Yes | Fields to return (resource fields, metrics, segments) |\n| `FROM` | Yes | Single resource type to query |\n| `WHERE` | No | Filter conditions joined by `AND` (no `OR` support) |\n| `ORDER BY` | No | Sort by one field, `ASC` or `DESC` |\n| `LIMIT` | No | Maximum number of rows to return |\n| `PARAMETERS` | No | Query-level parameters (e.g., `include_drafts = true`) |\n\n### Example\n\n```sql\nSELECT\n  campaign.name,\n  metrics.impressions,\n  metrics.clicks,\n  metrics.cost_micros\nFROM campaign\nWHERE campaign.status = 'ENABLED'\n  AND segments.date DURING LAST_30_DAYS\nORDER BY metrics.impressions DESC\nLIMIT 50\n```\n\n## Resource Types (FROM Clause)\n\n### Campaign Management\n\n| Resource | Description |\n|----------|-------------|\n| `campaign` | Campaign settings, status, bidding, budget |\n| `campaign_budget` | Shared and campaign-level budgets |\n| `campaign_criterion` | Campaign-level targeting criteria |\n| `campaign_bid_modifier` | Bid adjustments at campaign level |\n| `bidding_strategy` | Portfolio bidding strategies |\n\n### Ad Groups & Ads\n\n| Resource | Description |\n|----------|-------------|\n| `ad_group` | Ad group settings, status, targeting |\n| `ad_group_ad` | Ads within ad groups (RSA, ETA, etc.) |\n| `ad_group_ad_asset_view` | Asset-level performance for responsive ads |\n| `ad_group_criterion` | Keywords, audiences, and other criteria |\n| `ad_group_bid_modifier` | Bid adjustments at ad group level |\n\n### Performance Views\n\n| Resource | Description |\n|----------|-------------|\n| `keyword_view` | Keyword-level performance metrics |\n| `search_term_view` | Actual search queries that triggered ads |\n| `landing_page_view` | Landing page performance |\n| `geographic_view` | Performance by geographic location |\n| `location_view` | Performance by targeted/excluded location |\n| `age_range_view` | Performance by age range demographic |\n| `gender_view` | Performance by gender demographic |\n| `user_location_view` | Performance by user's physical location |\n| `display_keyword_view` | Display network keyword performance |\n| `topic_view` | Display/video topic targeting performance |\n| `managed_placement_view` | Managed placement performance |\n\n### Conversion & Attribution\n\n| Resource | Description |\n|----------|-------------|\n| `conversion_action` | Conversion action configuration |\n| `customer_conversion_goal` | Conversion goals and optimization settings |\n\n### Account & Extensions\n\n| Resource | Description |\n|----------|-------------|\n| `customer` | Account-level settings |\n| `asset` | Account assets (sitelinks, callouts, images) |\n| `asset_group` | Performance Max asset groups |\n| `asset_group_asset` | Assets within asset groups |\n\n### Change History\n\n| Resource | Description |\n|----------|-------------|\n| `change_status` | Recent changes to account entities |\n| `change_event` | Detailed change history with old/new values |\n\n## Common Fields\n\n### Campaign Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `campaign.id` | INT64 | Unique campaign ID |\n| `campaign.name` | STRING | Campaign name |\n| `campaign.status` | ENUM | `ENABLED`, `PAUSED`, `REMOVED` |\n| `campaign.advertising_channel_type` | ENUM | `SEARCH`, `DISPLAY`, `SHOPPING`, `VIDEO`, `PERFORMANCE_MAX` |\n| `campaign.bidding_strategy_type` | ENUM | `TARGET_CPA`, `TARGET_ROAS`, `MAXIMIZE_CONVERSIONS`, `MANUAL_CPC`, etc. |\n| `campaign.campaign_budget` | RESOURCE | Budget resource name |\n| `campaign.start_date` | DATE | Campaign start date |\n| `campaign.end_date` | DATE | Campaign end date |\n| `campaign.serving_status` | ENUM | `SERVING`, `NONE`, `ENDED`, `PENDING`, `SUSPENDED` |\n| `campaign.target_cpa.target_cpa_micros` | INT64 | Target CPA in micros |\n| `campaign.target_roas.target_roas` | DOUBLE | Target ROAS as a ratio |\n\n### Ad Group Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `ad_group.id` | INT64 | Unique ad group ID |\n| `ad_group.name` | STRING | Ad group name |\n| `ad_group.status` | ENUM | `ENABLED`, `PAUSED`, `REMOVED` |\n| `ad_group.type` | ENUM | `SEARCH_STANDARD`, `DISPLAY_STANDARD`, `SHOPPING_PRODUCT_ADS`, etc. |\n| `ad_group.cpc_bid_micros` | INT64 | Default CPC bid in micros |\n| `ad_group.target_cpa_micros` | INT64 | Ad group-level target CPA |\n\n### Ad Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `ad_group_ad.ad.id` | INT64 | Unique ad ID |\n| `ad_group_ad.ad.type` | ENUM | `RESPONSIVE_SEARCH_AD`, `EXPANDED_TEXT_AD`, etc. |\n| `ad_group_ad.ad.final_urls` | STRING (repeated) | Landing page URLs |\n| `ad_group_ad.status` | ENUM | `ENABLED`, `PAUSED`, `REMOVED` |\n| `ad_group_ad.ad.responsive_search_ad.headlines` | MESSAGE (repeated) | RSA headline assets |\n| `ad_group_ad.ad.responsive_search_ad.descriptions` | MESSAGE (repeated) | RSA description assets |\n| `ad_group_ad.policy_summary.approval_status` | ENUM | `APPROVED`, `DISAPPROVED`, etc. |\n\n### Keyword & Criterion Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `ad_group_criterion.criterion_id` | INT64 | Criterion ID |\n| `ad_group_criterion.keyword.text` | STRING | Keyword text |\n| `ad_group_criterion.keyword.match_type` | ENUM | `BROAD`, `PHRASE`, `EXACT` |\n| `ad_group_criterion.status` | ENUM | `ENABLED`, `PAUSED`, `REMOVED` |\n| `ad_group_criterion.quality_info.quality_score` | INT32 | Quality Score (1-10) |\n| `ad_group_criterion.quality_info.creative_quality_score` | ENUM | `BELOW_AVERAGE`, `AVERAGE`, `ABOVE_AVERAGE` |\n| `ad_group_criterion.quality_info.post_click_quality_score` | ENUM | Landing page experience |\n| `ad_group_criterion.quality_info.search_predicted_ctr` | ENUM | Expected CTR |\n| `ad_group_criterion.effective_cpc_bid_micros` | INT64 | Effective CPC bid |\n| `ad_group_criterion.position_estimates.first_page_cpc_micros` | INT64 | Estimated first page CPC |\n\n### Search Term Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `search_term_view.search_term` | STRING | Actual user search query |\n| `search_term_view.status` | ENUM | `ADDED`, `EXCLUDED`, `ADDED_EXCLUDED`, `NONE` |\n\n### Metrics\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `metrics.impressions` | INT64 | Number of impressions |\n| `metrics.clicks` | INT64 | Number of clicks |\n| `metrics.cost_micros` | INT64 | Cost in micros (divide by 1,000,000) |\n| `metrics.ctr` | DOUBLE | Click-through rate |\n| `metrics.average_cpc` | DOUBLE | Average CPC in micros |\n| `metrics.average_cpm` | DOUBLE | Average CPM in micros |\n| `metrics.conversions` | DOUBLE | Conversions |\n| `metrics.conversions_value` | DOUBLE | Total conversion value |\n| `metrics.cost_per_conversion` | DOUBLE | Cost per conversion in micros |\n| `metrics.all_conversions` | DOUBLE | All conversions (including cross-device) |\n| `metrics.all_conversions_value` | DOUBLE | All conversions value |\n| `metrics.view_through_conversions` | INT64 | View-through conversions |\n| `metrics.search_impression_share` | DOUBLE | Search impression share (0.0-1.0) |\n| `metrics.search_top_impression_share` | DOUBLE | Top impression share |\n| `metrics.search_absolute_top_impression_share` | DOUBLE | Absolute top impression share |\n| `metrics.search_budget_lost_impression_share` | DOUBLE | IS lost to budget |\n| `metrics.search_rank_lost_impression_share` | DOUBLE | IS lost to rank |\n| `metrics.interaction_rate` | DOUBLE | Interaction rate |\n| `metrics.interactions` | INT64 | Interactions |\n| `metrics.video_views` | INT64 | Video views |\n| `metrics.video_view_rate` | DOUBLE | Video view rate |\n| `metrics.invalid_clicks` | INT64 | Invalid clicks filtered by Google |\n\n### Segments\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `segments.date` | DATE | Date (YYYY-MM-DD) |\n| `segments.day_of_week` | ENUM | `MONDAY` through `SUNDAY` |\n| `segments.month` | DATE | First day of the month |\n| `segments.quarter` | DATE | First day of the quarter |\n| `segments.year` | INT32 | Year |\n| `segments.hour` | INT32 | Hour of day (0-23) |\n| `segments.device` | ENUM | `DESKTOP`, `MOBILE`, `TABLET`, `OTHER` |\n| `segments.ad_network_type` | ENUM | `SEARCH`, `SEARCH_PARTNERS`, `CONTENT`, `YOUTUBE_SEARCH`, `YOUTUBE_WATCH` |\n| `segments.slot` | ENUM | `TOP`, `OTHER` |\n| `segments.conversion_action` | RESOURCE | Conversion action resource name |\n| `segments.conversion_action_name` | STRING | Conversion action name |\n| `segments.conversion_action_category` | ENUM | Conversion action category |\n| `segments.click_type` | ENUM | `URL_CLICKS`, `CALLS`, `SITELINKS`, etc. |\n| `segments.keyword.info.text` | STRING | Keyword text (in search_term_view) |\n| `segments.keyword.info.match_type` | ENUM | Keyword match type |\n\n## WHERE Clause Operators\n\n### Comparison Operators\n\n| Operator | Example |\n|----------|---------|\n| `=` | `campaign.status = 'ENABLED'` |\n| `!=` | `campaign.status != 'REMOVED'` |\n| `>` | `metrics.impressions > 100` |\n| `<` | `metrics.ctr < 0.02` |\n| `>=` | `metrics.clicks >= 10` |\n| `<=` | `metrics.cost_micros <= 5000000` |\n\n### Set Operators\n\n| Operator | Example |\n|----------|---------|\n| `IN` | `campaign.status IN ('ENABLED', 'PAUSED')` |\n| `NOT IN` | `campaign.advertising_channel_type NOT IN ('VIDEO', 'DISPLAY')` |\n| `CONTAINS ANY` | `campaign.labels CONTAINS ANY ('customers/123/labels/456')` |\n| `CONTAINS ALL` | `campaign.labels CONTAINS ALL ('..label1..', '..label2..')` |\n| `CONTAINS NONE` | `campaign.labels CONTAINS NONE ('customers/123/labels/456')` |\n\n### String Operators\n\n| Operator | Example |\n|----------|---------|\n| `LIKE` | `campaign.name LIKE '%Brand%'` |\n| `NOT LIKE` | `campaign.name NOT LIKE '%Test%'` |\n\n### Null Checks\n\n| Operator | Example |\n|----------|---------|\n| `IS NULL` | `ad_group_criterion.quality_info.quality_score IS NULL` |\n| `IS NOT NULL` | `ad_group_criterion.quality_info.quality_score IS NOT NULL` |\n\n### Range Operators\n\n| Operator | Example |\n|----------|---------|\n| `BETWEEN` | `segments.date BETWEEN '2025-01-01' AND '2025-01-31'` |\n| `DURING` | `segments.date DURING LAST_30_DAYS` |\n\n### Date Macros (DURING)\n\n| Macro | Description |\n|-------|-------------|\n| `TODAY` | Today only |\n| `YESTERDAY` | Yesterday only |\n| `LAST_7_DAYS` | Last 7 days (not including today) |\n| `LAST_14_DAYS` | Last 14 days |\n| `LAST_30_DAYS` | Last 30 days |\n| `LAST_BUSINESS_WEEK` | Monday-Friday of previous week |\n| `THIS_WEEK_MON_TODAY` | Monday of this week through today |\n| `THIS_WEEK_SUN_TODAY` | Sunday of this week through today |\n| `THIS_MONTH` | First day of this month through today |\n| `LAST_MONTH` | Entire previous month |\n\n## Common Query Patterns\n\n### Campaign Performance Report\n\n```sql\nSELECT\n  campaign.id,\n  campaign.name,\n  campaign.status,\n  campaign.advertising_channel_type,\n  campaign.bidding_strategy_type,\n  metrics.impressions,\n  metrics.clicks,\n  metrics.ctr,\n  metrics.cost_micros,\n  metrics.conversions,\n  metrics.conversions_value,\n  metrics.cost_per_conversion\nFROM campaign\nWHERE campaign.status != 'REMOVED'\n  AND segments.date DURING LAST_30_DAYS\nORDER BY metrics.cost_micros DESC\n```\n\n### Search Terms Report (Negative Keyword Identification)\n\n```sql\nSELECT\n  search_term_view.search_term,\n  search_term_view.status,\n  segments.keyword.info.text,\n  segments.keyword.info.match_type,\n  campaign.name,\n  ad_group.name,\n  metrics.impressions,\n  metrics.clicks,\n  metrics.ctr,\n  metrics.cost_micros,\n  metrics.conversions,\n  metrics.cost_per_conversion\nFROM search_term_view\nWHERE campaign.status = 'ENABLED'\n  AND segments.date DURING LAST_30_DAYS\n  AND metrics.impressions > 10\nORDER BY metrics.cost_micros DESC\nLIMIT 1000\n```\n\nFilter for high-cost, zero-conversion terms to build negative keyword lists.\n\n### Quality Score Analysis\n\n```sql\nSELECT\n  campaign.name,\n  ad_group.name,\n  ad_group_criterion.keyword.text,\n  ad_group_criterion.keyword.match_type,\n  ad_group_criterion.quality_info.quality_score,\n  ad_group_criterion.quality_info.creative_quality_score,\n  ad_group_criterion.quality_info.post_click_quality_score,\n  ad_group_criterion.quality_info.search_predicted_ctr,\n  metrics.impressions,\n  metrics.clicks,\n  metrics.cost_micros,\n  metrics.conversions\nFROM keyword_view\nWHERE campaign.status = 'ENABLED'\n  AND ad_group.status = 'ENABLED'\n  AND ad_group_criterion.status = 'ENABLED'\n  AND ad_group_criterion.quality_info.quality_score IS NOT NULL\n  AND segments.date DURING LAST_30_DAYS\nORDER BY ad_group_criterion.quality_info.quality_score ASC\n```\n\n### Landing Page Performance\n\n```sql\nSELECT\n  landing_page_view.unexpanded_final_url,\n  metrics.impressions,\n  metrics.clicks,\n  metrics.ctr,\n  metrics.cost_micros,\n  metrics.conversions,\n  metrics.cost_per_conversion\nFROM landing_page_view\nWHERE campaign.status = 'ENABLED'\n  AND segments.date DURING LAST_30_DAYS\n  AND metrics.clicks > 0\nORDER BY metrics.clicks DESC\nLIMIT 100\n```\n\n### Device Breakdown\n\n```sql\nSELECT\n  campaign.name,\n  segments.device,\n  metrics.impressions,\n  metrics.clicks,\n  metrics.ctr,\n  metrics.cost_micros,\n  metrics.conversions,\n  metrics.cost_per_conversion\nFROM campaign\nWHERE campaign.status = 'ENABLED'\n  AND segments.date DURING LAST_30_DAYS\nORDER BY campaign.name, segments.device\n```\n\n### Geographic Performance\n\n```sql\nSELECT\n  geographic_view.country_criterion_id,\n  geographic_view.location_type,\n  campaign.name,\n  metrics.impressions,\n  metrics.clicks,\n  metrics.ctr,\n  metrics.cost_micros,\n  metrics.conversions,\n  metrics.conversions_value,\n  metrics.cost_per_conversion\nFROM geographic_view\nWHERE campaign.status = 'ENABLED'\n  AND segments.date DURING LAST_30_DAYS\n  AND metrics.impressions > 0\nORDER BY metrics.cost_micros DESC\nLIMIT 200\n```\n\n### Ad Copy Performance (RSA Asset-Level)\n\n```sql\nSELECT\n  campaign.name,\n  ad_group.name,\n  ad_group_ad.ad.id,\n  ad_group_ad.ad.responsive_search_ad.headlines,\n  ad_group_ad.ad.responsive_search_ad.descriptions,\n  ad_group_ad.ad.final_urls,\n  metrics.impressions,\n  metrics.clicks,\n  metrics.ctr,\n  metrics.cost_micros,\n  metrics.conversions\nFROM ad_group_ad\nWHERE campaign.status = 'ENABLED'\n  AND ad_group.status = 'ENABLED'\n  AND ad_group_ad.status = 'ENABLED'\n  AND ad_group_ad.ad.type = 'RESPONSIVE_SEARCH_AD'\n  AND segments.date DURING LAST_30_DAYS\nORDER BY metrics.impressions DESC\n```\n\nAsset-level performance:\n\n```sql\nSELECT\n  campaign.name,\n  ad_group.name,\n  ad_group_ad_asset_view.field_type,\n  ad_group_ad_asset_view.performance_label,\n  asset.text_asset.text,\n  metrics.impressions,\n  metrics.clicks,\n  metrics.ctr,\n  metrics.cost_micros,\n  metrics.conversions\nFROM ad_group_ad_asset_view\nWHERE campaign.status = 'ENABLED'\n  AND ad_group.status = 'ENABLED'\n  AND segments.date DURING LAST_30_DAYS\nORDER BY ad_group_ad_asset_view.performance_label DESC, metrics.impressions DESC\n```\n\n### Budget Utilization / Impression Share\n\n```sql\nSELECT\n  campaign.name,\n  campaign.campaign_budget,\n  campaign_budget.amount_micros,\n  campaign.bidding_strategy_type,\n  metrics.impressions,\n  metrics.cost_micros,\n  metrics.search_impression_share,\n  metrics.search_top_impression_share,\n  metrics.search_absolute_top_impression_share,\n  metrics.search_budget_lost_impression_share,\n  metrics.search_rank_lost_impression_share\nFROM campaign\nWHERE campaign.status = 'ENABLED'\n  AND campaign.advertising_channel_type = 'SEARCH'\n  AND segments.date DURING LAST_30_DAYS\nORDER BY metrics.search_budget_lost_impression_share DESC\n```\n\n### Conversion Action Breakdown\n\n```sql\nSELECT\n  campaign.name,\n  segments.conversion_action_name,\n  segments.conversion_action_category,\n  metrics.conversions,\n  metrics.conversions_value,\n  metrics.all_conversions,\n  metrics.all_conversions_value,\n  metrics.cost_per_conversion\nFROM campaign\nWHERE campaign.status = 'ENABLED'\n  AND segments.date DURING LAST_30_DAYS\n  AND metrics.conversions > 0\nORDER BY metrics.conversions DESC\n```\n\n### Change History Audit\n\n```sql\nSELECT\n  change_event.change_date_time,\n  change_event.change_resource_type,\n  change_event.change_resource_name,\n  change_event.resource_change_operation,\n  change_event.changed_fields,\n  change_event.old_resource,\n  change_event.new_resource,\n  change_event.user_email\nFROM change_event\nWHERE change_event.change_date_time DURING LAST_14_DAYS\n  AND change_event.change_resource_type IN (\n    'CAMPAIGN', 'AD_GROUP', 'AD_GROUP_AD',\n    'AD_GROUP_CRITERION', 'CAMPAIGN_BUDGET'\n  )\nORDER BY change_event.change_date_time DESC\nLIMIT 500\n```\n\n## Gotchas and Important Notes\n\n### cost_micros Requires Division\n\nAll cost fields are in micros (1/1,000,000 of the currency unit):\n\n```\nActual cost = metrics.cost_micros / 1,000,000\nActual CPC  = metrics.average_cpc / 1,000,000\n```\n\nExample: `cost_micros = 5430000` means $5.43.\n\n### Segment + Metric Compatibility\n\n- `segments.conversion_action` — impressions/clicks repeat across each conversion action row. Do not sum them.\n- `segments.click_type` — clicks and impressions fragment by click type. Summing overcounts.\n- `segments.slot` — only compatible with search campaigns.\n- `segments.hour` — cannot be combined with `segments.date` for some resources.\n- Check the Google Ads API field compatibility matrix when in doubt.\n\n### Date Range Requirements\n\n- Queries with `metrics.*` fields require a date range (`segments.date DURING ...` or `BETWEEN`).\n- Resource-only queries (no metrics) do not need a date range.\n\n### Enum Values\n\nEnum fields must use string constant names:\n\n- **CampaignStatus:** `ENABLED`, `PAUSED`, `REMOVED`\n- **AdGroupStatus:** `ENABLED`, `PAUSED`, `REMOVED`\n- **AdvertisingChannelType:** `SEARCH`, `DISPLAY`, `SHOPPING`, `VIDEO`, `PERFORMANCE_MAX`, `MULTI_CHANNEL`, `LOCAL`, `SMART`, `HOTEL`, `DISCOVERY`\n- **KeywordMatchType:** `BROAD`, `PHRASE`, `EXACT`\n- **BiddingStrategyType:** `TARGET_CPA`, `TARGET_ROAS`, `MAXIMIZE_CONVERSIONS`, `MAXIMIZE_CONVERSION_VALUE`, `MANUAL_CPC`, `ENHANCED_CPC`, `TARGET_IMPRESSION_SHARE`\n- **Device:** `DESKTOP`, `MOBILE`, `TABLET`, `CONNECTED_TV`, `OTHER`\n- **QualityScoreBucket:** `BELOW_AVERAGE`, `AVERAGE`, `ABOVE_AVERAGE`\n\n### Rate Limits\n\n- **Standard access:** 15,000 requests/day, 1,600 operations/minute.\n- **Basic access:** 10,000 requests/day.\n- Use `SearchStream` for large result sets (one operation regardless of size).\n\n### Other Pitfalls\n\n- **No `OR`:** All WHERE conditions are AND-joined. Use `IN` or separate queries.\n- **No joins:** GAQL queries operate on a single resource.\n- **No `GROUP BY`:** Aggregation is implicit by selected fields + segments.\n- **No aliases:** Cannot use `AS` in GAQL.\n- **No arithmetic:** Calculate `cost_micros / 1000000` client-side.\n- **Segment auto-grouping:** Adding a segment splits rows by that dimension.\n- **Removed resources:** Excluded by default. Filter explicitly to include them.\n- **PARAMETERS clause:** `include_drafts = true` for drafts, `omit_unselected_resource_names = true` to reduce response size.\n\n## Resources\n\n- **GAQL Grammar:** https://developers.google.com/google-ads/api/docs/query/grammar\n- **Interactive Query Builder:** https://developers.google.com/google-ads/api/fields/v17/overview_query_builder\n- **Resource Reference:** https://developers.google.com/google-ads/api/fields/v17/overview\n- **Rate Limits:** https://developers.google.com/google-ads/api/docs/best-practices/rate-limits\n- **Full Cogny Docs:** https://cogny.com/docs/gaql-reference","tags":["gaql","reference","claude","code","marketing","skills","cognyai","agent-skills","ai-agents","claude-code","claude-skills","cluade-mcp"],"capabilities":["skill","source-cognyai","skill-gaql-reference","topic-agent-skills","topic-ai-agents","topic-claude-code","topic-claude-skills","topic-cluade-mcp","topic-cursor","topic-geo","topic-growth-hacking","topic-llm","topic-marketing","topic-mcp","topic-seo"],"categories":["claude-code-marketing-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/cognyai/claude-code-marketing-skills/gaql-reference","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add cognyai/claude-code-marketing-skills","source_repo":"https://github.com/cognyai/claude-code-marketing-skills","install_from":"skills.sh"}},"qualityScore":"0.471","qualityRationale":"deterministic score 0.47 from registry signals: · indexed on github topic:agent-skills · 42 github stars · SKILL.md body (21,198 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-01T06:56:26.518Z","embedding":null,"createdAt":"2026-04-18T22:23:34.370Z","updatedAt":"2026-05-01T06:56:26.518Z","lastSeenAt":"2026-05-01T06:56:26.518Z","tsv":"'-01':1236,1237,1240 '-1.0':965 '-10':809 '-23':1073 '-31':1241 '/docs/gaql-reference':56,2182 '/gaql-reference':58,63,70,77,84,89 '/google-ads/api/docs/best-practices/rate-limits':2176 '/google-ads/api/docs/query/grammar':2160 '/google-ads/api/fields/v17/overview':2171 '/google-ads/api/fields/v17/overview_query_builder':2166 '0':1072,1517,1589,1790 '0.0':964 '0.02':1153 '000':893,894,1870,1871,1881,1882,1888,1889,2045,2053 '1':808,892,1880,1887,2047 '1/1':1869 '10':1155,1407,2052 '100':1151,1523 '1000':1414 '1000000':2113 '14':1269,1272,1829 '15':2044 '200':1596 '2025':1235,1239 '30':345,1246,1275,1278,1360,1403,1478,1513,1548,1585,1641,1682,1744,1786 '5.43':1895 '50':352 '500':1854 '5000000':1158 '5430000':1893 '600':2048 '7':1260,1263 'absolut':975,980,1716 'access':2043,2051 'account':544,550,554,581 'account-level':549 'across':1903 'action':141,532,534,1097,1100,1104,1108,1111,1115,1755,1761,1764,1900,1906 'actual':461,859,1876,1883 'ad':5,26,48,101,188,200,209,395,397,400,402,407,409,410,412,417,419,428,429,437,444,466,677,686,691,707,722,728,736,742,745,865,867,1597,1620,1622,1636,1667,1669,1837,1839,1841,1842,1941,2121 'ad_group.cpc':709 'ad_group.id':683 'ad_group.name':689,1382,1435,1607,1654 'ad_group.status':694,1463,1627,1676 'ad_group.target':718 'ad_group.type':699 'ad_group_ad.ad.final':747,1611 'ad_group_ad.ad.id':733,1608 'ad_group_ad.ad.responsive_search_ad.descriptions':765,1610 'ad_group_ad.ad.responsive_search_ad.headlines':759,1609 'ad_group_ad.ad.type':738,1633 'ad_group_ad.policy_summary.approval':771 'ad_group_ad.status':754,1630 'ad_group_ad_asset_view.field':1655 'ad_group_ad_asset_view.performance':1657,1686 'ad_group_criterion.criterion':783 'ad_group_criterion.effective':833 'ad_group_criterion.keyword.match':792,1437 'ad_group_criterion.keyword.text':788,1436 'ad_group_criterion.position_estimates.first':841 'ad_group_criterion.quality_info.creative':810,1441 'ad_group_criterion.quality_info.post':819,1444 'ad_group_criterion.quality_info.quality':803,1216,1223,1439,1469,1482 'ad_group_criterion.quality_info.search':827,1448 'ad_group_criterion.status':798,1466 'adgroupstatus':1989 'adjust':386,442 'advertisingchanneltyp':1993 'age':485,490 'aggreg':2094 'alias':2102 'analysi':75,1431 'and-join':2074 'answer':142 'api':216,1942 'approv':774 'area':163 'argument':159 'arithmet':2109 'asc':236,307,1484 'ask':130 'asset':420,423,553,555,559,563,565,567,568,570,764,770,1602,1648,1670 'asset-level':422,1601,1647 'asset.text_asset.text':1659 'attribut':528 'audienc':433 'audit':94,1797 'auto':2119 'auto-group':2118 'avail':173,182 'averag':815,816,818,904,911,2036,2037,2039 'avoid':124 'basic':2050 'bid':365,383,385,390,393,439,441,710,715,835,840 'biddingstrategytyp':2010 'brand':1203 'breakdown':1525,1756 'broad':795,2007 'budget':80,366,368,374,636,638,985,993,1691,1699,1721,1749,1846 'build':1425 'builder':2163 'busi':1281 'calcul':2110 'call':1122 'callout':557 'campaign':337,357,361,362,367,372,375,378,382,388,593,601,605,644,650,1326,1352,1540,1731,1778,1836,1845,1928 'campaign-level':371,377 'campaign.advertising':612,1170,1334,1736 'campaign.bidding':622,1337,1702 'campaign.campaign':635,1698 'campaign.end':647 'campaign.id':598,1331 'campaign.labels':1179,1185,1192 'campaign.name':331,603,1201,1206,1332,1381,1434,1528,1552,1563,1606,1653,1697,1759 'campaign.serving':653 'campaign.start':641 'campaign.status':339,607,1146,1148,1164,1333,1354,1397,1460,1507,1542,1579,1624,1673,1733,1780 'campaign.target_cpa.target':661 'campaign.target_roas.target':669 'campaign_budget.amount':1700 'campaignstatus':1985 'cannot':1930,2103 'categori':1112,1116,1765 'chang':90,92,572,576,579,583,586,1795,1810,1821 'change_event.change':1800,1803,1806,1824,1832,1849 'change_event.changed':1812 'change_event.new':1816 'change_event.old':1814 'change_event.resource':1809 'change_event.user':1818 'channel':613,1171,1335,1737,2001 'check':1211,1938 'choos':119 'claus':270,271,356,1140,2140 'click':820,883,898,1025,1028,1121,1445,1914,1919 'click-through':897 'client':2115 'client-sid':2114 'cogni':179,186,198,207,2178 'cogny.com':55,2181 'cogny.com/docs/gaql-reference':54,2180 'combin':1932 'common':43,125,591,1323 'comparison':1142 'compat':1898,1925,1944 'complet':10,31 'condit':230,250,252,254,255,293,2072 'configur':535 'connect':2031 'constant':1983 'contain':1177,1180,1183,1186,1190,1193 'content':1087 'convers':527,531,533,537,539,631,917,922,926,930,934,937,943,947,951,956,1099,1107,1114,1350,1391,1422,1501,1538,1574,1754,1770,1772,1776,1905,2016,2018 'copi':1598 'correct':113 'cost':887,928,1419,1859,1864,1877,1891,2111 'cpa':627,662,666,719,727,2012 'cpc':633,714,834,839,843,849,902,905,1884,1886,2021,2023 'cpm':909,912 'criteria':381,436 'criterion':376,431,778,786,1559,1844 'cross':940 'cross-devic':939 'ctr':829,832,1450 'currenc':1874 'custom':536,548 'customers/123/labels/456':1182,1195 'date':16,40,642,643,646,648,649,652,1037,1038,1051,1058,1248,1801,1825,1850,1949,1958,1974 'day':346,1053,1060,1071,1247,1261,1264,1270,1273,1276,1279,1312,1361,1404,1479,1514,1549,1586,1642,1683,1745,1787,1830 'dd':1042 'default':713,2133 'demograph':492,498 'desc':237,309,350,1366,1412,1521,1594,1646,1688,1690,1753,1794,1852 'descript':273,360,399,450,530,547,575,597,682,732,769,782,855,873,1035,1252 'desktop':1076,2028 'detail':585 'developers.google.com':2159,2165,2170,2175 'developers.google.com/google-ads/api/docs/best-practices/rate-limits':2174 'developers.google.com/google-ads/api/docs/query/grammar':2158 'developers.google.com/google-ads/api/fields/v17/overview':2169 'developers.google.com/google-ads/api/fields/v17/overview_query_builder':2164 'devic':941,1524,2027 'dimens':2128 'direct':195 'disapprov':775 'discoveri':2005 'display':508,511,617,703,1176,1995 'display/video':517 'divid':890 'divis':1862 'doc':53,204,214,2179 'document':217 'doubl':671,896,903,910,916,920,927,935,945,960,970,979,989,999,1006,1020 'doubt':1948 'draft':326,2142,2145 'e.g':324 'effect':838 'email':1819 'enabl':340,609,696,756,800,1147,1166,1398,1461,1464,1467,1508,1543,1580,1625,1628,1631,1674,1677,1734,1781,1986,1990 'end':651,658 'enhanc':2022 'entir':1320 'entiti':582 'enum':608,615,625,655,695,700,739,755,773,794,799,813,823,830,864,1046,1075,1083,1093,1113,1119,1135,1976,1978 'estim':846 'eta':415 'etc':416,634,708,746,776,1124 'event':584,1822 'exact':797,2009 'exampl':149,328,1145,1162,1199,1213,1231,1890 'exclud':866,868,2131 'execut':190 'expand':743 'expect':831 'experi':826 'expert':105 'explicit':2135 'extens':545 'field':14,38,122,224,234,244,246,248,256,276,280,306,592,594,595,679,680,729,730,779,780,852,853,871,1033,1813,1865,1943,1955,1979,2099 'filter':292,1029,1415,2134 'final':1491 'find':133 'first':847,1052,1059,1311 'focus':160 'formal':220 'fragment':1917 'friday':1285 'full':52,60,2177 'gaql':2,8,29,34,104,114,148,170,191,203,2084,2107,2156 'gaql-refer':1 'gender':493,497 'geograph':85,86,473,477,1554,1576 'geographic_view.country':1558 'geographic_view.location':1561 'get':202,211 'goal':538,540 'googl':4,25,47,100,187,199,208,1031,1940 'gotcha':1855 'grammar':221,2157 'group':396,401,403,408,413,418,430,438,445,560,564,566,571,678,687,692,724,1621,1668,1838,1840,1843,2092,2120 'group-level':723 'headlin':763 'help':110 'high':1418 'high-cost':1417 'histori':91,93,573,587,1796 'hotel':2004 'hour':1069 'id':602,688,737,784,787,1560 'identif':1372 'imag':558 'implicit':2096 'import':1857 'impress':78,81,878,958,962,968,972,977,982,987,997,1693,1709,1713,1718,1723,1728,1751,1916,2025 'impressions/clicks':1901 'includ':325,938,1266,2137,2141 'instruct':96 'int32':805,1065,1068 'int64':599,664,684,712,721,734,785,837,845,875,880,886,952,1010,1014,1026 'integ':240 'interact':1007,1011,2161 'invalid':1027 'join':294,2076,2083 'keyword':432,451,454,509,513,777,790,1127,1136,1371,1427,1457 'keyword-level':453 'keywordmatchtyp':2006 'label':1658,1687 'label1':1188 'label2':1189 'land':467,470,751,824,1485,1503 'landing_page_view.unexpanded':1490 'languag':7,28,103 'larg':2058 'last':344,1245,1259,1262,1268,1271,1274,1277,1280,1318,1359,1402,1477,1512,1547,1584,1640,1681,1743,1785,1828 'level':322,373,379,389,424,446,455,551,725,1603,1649 'like':1200,1202,1205,1208 'limit':238,310,351,1413,1522,1595,1853,2041,2173 'list':225,231,243,245,251,261,1428 'local':2002 'locat':478,479,484,500,507 'lookup':218 'lost':986,991,996,1001,1722,1727,1750 'macro':17,41,1249,1251 'manag':358,521,524 'manual':632,2020 'match':1137 'matrix':1945 'max':562,621,1999 'maxim':630,2015,2017 'maximum':312 'mcp':180,185,197,206 'mean':1894 'messag':760,766 'metric':281,457,870,1897,1954,1969 'metrics.all':933,942,1769,1771 'metrics.average':901,908,1885 'metrics.clicks':333,879,1154,1341,1384,1452,1494,1516,1520,1531,1565,1614,1661 'metrics.conversions':915,918,1345,1346,1388,1455,1498,1535,1569,1570,1618,1665,1766,1767,1789,1793 'metrics.cost':334,884,924,1156,1343,1348,1364,1386,1389,1410,1453,1496,1499,1533,1536,1567,1572,1592,1616,1663,1706,1774,1878 'metrics.ctr':895,1152,1342,1385,1495,1532,1566,1615,1662 'metrics.impressions':332,349,874,1150,1340,1383,1406,1451,1493,1530,1564,1588,1613,1645,1660,1689,1705 'metrics.interaction':1004 'metrics.interactions':1009 'metrics.invalid':1024 'metrics.search':957,966,974,984,994,1708,1711,1715,1720,1725,1748 'metrics.video':1012,1017 'metrics.view':949 'micro':335,663,668,711,717,720,836,844,885,889,907,914,932,1157,1344,1365,1387,1411,1454,1497,1534,1568,1593,1617,1664,1701,1707,1860,1868,1879,1892,2112 'mm':1041 'mobil':1077,2029 'modifi':384,440 'mon':1291 'monday':1047,1284,1293 'monday-friday':1283 'month':1056,1310,1315,1319,1322 'multi':2000 'must':1980 'name':228,235,247,249,257,263,267,606,640,693,1102,1105,1109,1762,1808,1984,2149 'need':1972 'negat':1370,1426 'network':512,1081 'none':657,869,1191,1194 'note':1858 'null':1210,1215,1219,1222,1227,1473 'number':313,876,881 'old/new':589 'omit':2146 'one':305,2061 'oper':15,39,258,1141,1143,1144,1160,1161,1197,1198,1212,1229,1230,1811,2062,2086 'operations/minute':2049 'optim':51,542 'order':232,300,347,1362,1408,1480,1518,1550,1590,1643,1684,1746,1791,1847 'otherwis':164 'overcount':1922 'overview':62,167 'page':468,471,752,825,842,848,1486,1504 'param':242,260,262,264,266,268 'paramet':241,318,323,2139 'partner':1086 'pattern':24,45,69,1325 'paus':610,697,757,801,1167,1987,1991 'pend':659 'per':925,929,1349,1390,1500,1537,1573,1775 'perform':87,425,447,456,472,475,481,488,495,502,514,520,526,561,620,1327,1487,1555,1599,1650,1998 'phrase':796,2008 'physic':506 'pitfal':126,2067 'placement':522,525 'portfolio':392 'posit':239 'precis':140 'predict':828,1449 'prefer':183 'previous':1287,1321 'product':706 'provid':139,153,165 'qualiti':71,73,806,811,821,1429,1442,1446 'qualityscorebucket':2034 'quarter':1063 'queri':6,23,27,44,76,83,88,95,102,115,194,222,289,321,463,862,1324,1952,1967,2081,2085,2162 'query-level':320 'question':132 'rang':486,491,1228,1950,1959,1975 'rank':995,1003,1726 'rate':900,1005,1008,1019,1023,2040,2172 'ratio':676 'readi':20,145 'ready-to-us':19,144 'recent':578 'reduc':2152 'refer':3,9,30,32,108,2168 'regardless':2063 'relev':135 'remov':611,698,758,802,1149,1355,1988,1992,2129 'repeat':750,761,767,1902 'report':49,68,212,1328,1369 'requests/day':2046,2054 'requir':272,1861,1951,1956 'resourc':12,36,117,174,227,279,286,353,359,398,449,529,546,574,637,639,1098,1101,1804,1807,1815,1817,1833,1937,1965,2090,2130,2148,2155,2167 'resource-on':1964 'respons':427,740,1634,2153 'result':2059 'return':278,317 'right':121 'roa':629,670,673,2014 'row':315,1907,2125 'rsa':414,762,768,1600 'run':193 'score':72,74,804,807,812,822,1217,1224,1430,1440,1443,1447,1470,1483 'search':64,66,458,462,616,701,741,850,861,961,1084,1085,1089,1130,1367,1393,1635,1739,1927,1994 'search_term_view.search':856,1375 'search_term_view.status':863,1377 'searchstream':2056 'section':136 'segment':282,1032,1896,2100,2117,2123 'segments.ad':1080 'segments.click':1117,1912 'segments.conversion':1096,1103,1110,1760,1763,1899 'segments.date':342,1036,1233,1243,1357,1400,1475,1510,1545,1582,1638,1679,1741,1783,1934,1960 'segments.day':1043 'segments.device':1074,1529,1553 'segments.hour':1067,1929 'segments.keyword.info.match':1133,1379 'segments.keyword.info.text':1125,1378 'segments.month':1050 'segments.quarter':1057 'segments.slot':1092,1923 'segments.year':1064 'select':223,274,330,1330,1374,1433,1489,1527,1557,1605,1652,1696,1758,1799,2098 'separ':2080 'serv':656 'set':363,404,543,552,1159,2060 'share':79,82,369,959,963,969,973,978,983,988,998,1694,1710,1714,1719,1724,1729,1752,2026 'shop':618,705,1996 'show':59 'side':2116 'singl':285,2089 'sitelink':556,1123 'size':2065,2154 'skill' 'skill-gaql-reference' 'smart':2003 'sort':303 'source-cognyai' 'specif':155 'split':2124 'sql':329,1329,1373,1432,1488,1526,1556,1604,1651,1695,1757,1798 'standard':702,704,2042 'start':645 'status':364,405,577,654,772 'strategi':391,394,623,1338,1703 'string':604,690,749,789,858,1106,1126,1196,1982 'sum':1910,1921 'sun':1301 'sunday':1049,1303 'support':299 'suspend':660 'syntax':11,35,61,171,219 'tablet':1078,2030 'target':380,406,519,626,628,665,672,726,2011,2013,2024 'targeted/excluded':483 'term':65,67,459,851,857,1131,1368,1376,1394,1423 'test':1209 'text':744,791,1128 'time':1802,1826,1851 'today':1253,1254,1267,1292,1298,1302,1308,1317 'tool':181,189,201,210 'top':967,971,976,981,1094,1712,1717 'topic':156,515,518 'topic-agent-skills' 'topic-ai-agents' 'topic-claude-code' 'topic-claude-skills' 'topic-cluade-mcp' 'topic-cursor' 'topic-geo' 'topic-growth-hacking' 'topic-llm' 'topic-marketing' 'topic-mcp' 'topic-seo' 'total':921 'trigger':465 'true':327,2143,2150 'tv':2032 'type':13,37,118,287,354,596,614,624,681,731,781,793,854,872,1034,1082,1118,1134,1138,1172,1336,1339,1380,1438,1562,1656,1704,1738,1805,1834,1913,1920 'understand':116 'uniqu':600,685,735 'unit':1875 'unselect':2147 'url':748,753,1120,1492,1612 'usag':57 'use':22,106,147,184,1981,2055,2077,2104 'user':111,129,152,177,499,504,860 'util':1692 'valu':259,265,269,590,919,923,944,948,1347,1571,1768,1773,1977,2019 'video':619,1015,1021,1175,1997 'view':213,421,448,452,460,469,474,480,487,494,501,510,516,523,954,1013,1016,1018,1022,1132,1395,1458,1505,1577,1671 'view-through':953 'watch':1091 'week':1045,1282,1288,1290,1296,1300,1306 'within':411,569 'write':112 'year':1066 'yes':275,284 'yesterday':1256,1257 'youtub':1088,1090 'yyyi':1040 'yyyy-mm-dd':1039 'zero':1421 'zero-convers':1420","prices":[{"id":"1d4e4d76-a37b-4268-95bf-9bd9bc2d3547","listingId":"644f4492-4480-46eb-9f09-7fc0dfb53814","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"cognyai","category":"claude-code-marketing-skills","install_from":"skills.sh"},"createdAt":"2026-04-18T22:23:34.370Z"}],"sources":[{"listingId":"644f4492-4480-46eb-9f09-7fc0dfb53814","source":"github","sourceId":"cognyai/claude-code-marketing-skills/gaql-reference","sourceUrl":"https://github.com/cognyai/claude-code-marketing-skills/tree/main/skills/gaql-reference","isPrimary":false,"firstSeenAt":"2026-04-18T22:23:34.370Z","lastSeenAt":"2026-05-01T06:56:26.518Z"}],"details":{"listingId":"644f4492-4480-46eb-9f09-7fc0dfb53814","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"cognyai","slug":"gaql-reference","github":{"repo":"cognyai/claude-code-marketing-skills","stars":42,"topics":["agent-skills","ai-agents","claude-code","claude-skills","cluade-mcp","cursor","geo","growth-hacking","llm","marketing","mcp","seo","vibe","windsurf"],"license":null,"html_url":"https://github.com/cognyai/claude-code-marketing-skills","pushed_at":"2026-04-29T13:43:50Z","description":"Marketing skills for Claude Code — SEO audits and implementation, ad analysis, ad optimization. Free skills need no account. $9/mo for live Search Console, Bing & LinkedIn data.","skill_md_sha":"ef14059cc9e7026776d9b1881206abbdfee5ceb2","skill_md_path":"skills/gaql-reference/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/cognyai/claude-code-marketing-skills/tree/main/skills/gaql-reference"},"layout":"multi","source":"github","category":"claude-code-marketing-skills","frontmatter":{"name":"gaql-reference","description":"Google Ads Query Language (GAQL) Reference — complete syntax, resource types, fields, operators, date macros, and ready-to-use query patterns"},"skills_sh_url":"https://skills.sh/cognyai/claude-code-marketing-skills/gaql-reference"},"updatedAt":"2026-05-01T06:56:26.518Z"}}