gaql-reference

Google Ads Query Language (GAQL) Reference

Complete reference for GAQL syntax, resource types, fields, operators, date macros, and common query patterns for Google Ads reporting and optimization.

Full docs: https://cogny.com/docs/gaql-reference

Usage

/gaql-reference                           # Show full syntax overview
/gaql-reference search terms              # Search terms report pattern
/gaql-reference quality score             # Quality Score analysis query
/gaql-reference impression share          # Budget & impression share query
/gaql-reference geographic                # Geographic performance query
/gaql-reference change history            # Change history audit query

Instructions

You 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.

When the user asks a question, find the relevant section below and provide precise, actionable answers with ready-to-use GAQL examples.

If the user provides a specific topic as an argument, focus on that area. Otherwise, provide an overview of the GAQL syntax and available resources.

When 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.

Syntax

Formal Grammar

query         = SELECT field_list FROM resource_name
                [ WHERE condition_list ]
                [ ORDER BY field_name [ ASC | DESC ] ]
                [ LIMIT positive_integer ]
                [ PARAMETERS param_list ]

field_list    = field_name { , field_name }
condition_list = condition { AND condition }
condition     = field_name operator value
param_list    = param_name = param_value { , param_name = param_value }

Clauses

| Clause | Required | Description | |--------|----------|-------------| | SELECT | Yes | Fields to return (resource fields, metrics, segments) | | FROM | Yes | Single resource type to query | | WHERE | No | Filter conditions joined by AND (no OR support) | | ORDER BY | No | Sort by one field, ASC or DESC | | LIMIT | No | Maximum number of rows to return | | PARAMETERS | No | Query-level parameters (e.g., include_drafts = true) |

Example

SELECT
  campaign.name,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC
LIMIT 50

Resource Types (FROM Clause)

Campaign Management

| Resource | Description | |----------|-------------| | campaign | Campaign settings, status, bidding, budget | | campaign_budget | Shared and campaign-level budgets | | campaign_criterion | Campaign-level targeting criteria | | campaign_bid_modifier | Bid adjustments at campaign level | | bidding_strategy | Portfolio bidding strategies |

Ad Groups & Ads

| Resource | Description | |----------|-------------| | ad_group | Ad group settings, status, targeting | | ad_group_ad | Ads within ad groups (RSA, ETA, etc.) | | ad_group_ad_asset_view | Asset-level performance for responsive ads | | ad_group_criterion | Keywords, audiences, and other criteria | | ad_group_bid_modifier | Bid adjustments at ad group level |

Performance Views

| Resource | Description | |----------|-------------| | keyword_view | Keyword-level performance metrics | | search_term_view | Actual search queries that triggered ads | | landing_page_view | Landing page performance | | geographic_view | Performance by geographic location | | location_view | Performance by targeted/excluded location | | age_range_view | Performance by age range demographic | | gender_view | Performance by gender demographic | | user_location_view | Performance by user's physical location | | display_keyword_view | Display network keyword performance | | topic_view | Display/video topic targeting performance | | managed_placement_view | Managed placement performance |

Conversion & Attribution

| Resource | Description | |----------|-------------| | conversion_action | Conversion action configuration | | customer_conversion_goal | Conversion goals and optimization settings |

Account & Extensions

| Resource | Description | |----------|-------------| | customer | Account-level settings | | asset | Account assets (sitelinks, callouts, images) | | asset_group | Performance Max asset groups | | asset_group_asset | Assets within asset groups |

Change History

| Resource | Description | |----------|-------------| | change_status | Recent changes to account entities | | change_event | Detailed change history with old/new values |

Common Fields

Campaign Fields

| Field | Type | Description | |-------|------|-------------| | campaign.id | INT64 | Unique campaign ID | | campaign.name | STRING | Campaign name | | campaign.status | ENUM | ENABLED, PAUSED, REMOVED | | campaign.advertising_channel_type | ENUM | SEARCH, DISPLAY, SHOPPING, VIDEO, PERFORMANCE_MAX | | campaign.bidding_strategy_type | ENUM | TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSIONS, MANUAL_CPC, etc. | | campaign.campaign_budget | RESOURCE | Budget resource name | | campaign.start_date | DATE | Campaign start date | | campaign.end_date | DATE | Campaign end date | | campaign.serving_status | ENUM | SERVING, NONE, ENDED, PENDING, SUSPENDED | | campaign.target_cpa.target_cpa_micros | INT64 | Target CPA in micros | | campaign.target_roas.target_roas | DOUBLE | Target ROAS as a ratio |

Ad Group Fields

| Field | Type | Description | |-------|------|-------------| | ad_group.id | INT64 | Unique ad group ID | | ad_group.name | STRING | Ad group name | | ad_group.status | ENUM | ENABLED, PAUSED, REMOVED | | ad_group.type | ENUM | SEARCH_STANDARD, DISPLAY_STANDARD, SHOPPING_PRODUCT_ADS, etc. | | ad_group.cpc_bid_micros | INT64 | Default CPC bid in micros | | ad_group.target_cpa_micros | INT64 | Ad group-level target CPA |

Ad Fields

| Field | Type | Description | |-------|------|-------------| | ad_group_ad.ad.id | INT64 | Unique ad ID | | ad_group_ad.ad.type | ENUM | RESPONSIVE_SEARCH_AD, EXPANDED_TEXT_AD, etc. | | ad_group_ad.ad.final_urls | STRING (repeated) | Landing page URLs | | ad_group_ad.status | ENUM | ENABLED, PAUSED, REMOVED | | ad_group_ad.ad.responsive_search_ad.headlines | MESSAGE (repeated) | RSA headline assets | | ad_group_ad.ad.responsive_search_ad.descriptions | MESSAGE (repeated) | RSA description assets | | ad_group_ad.policy_summary.approval_status | ENUM | APPROVED, DISAPPROVED, etc. |

Keyword & Criterion Fields

| Field | Type | Description | |-------|------|-------------| | ad_group_criterion.criterion_id | INT64 | Criterion ID | | ad_group_criterion.keyword.text | STRING | Keyword text | | ad_group_criterion.keyword.match_type | ENUM | BROAD, PHRASE, EXACT | | ad_group_criterion.status | ENUM | ENABLED, PAUSED, REMOVED | | ad_group_criterion.quality_info.quality_score | INT32 | Quality Score (1-10) | | ad_group_criterion.quality_info.creative_quality_score | ENUM | BELOW_AVERAGE, AVERAGE, ABOVE_AVERAGE | | ad_group_criterion.quality_info.post_click_quality_score | ENUM | Landing page experience | | ad_group_criterion.quality_info.search_predicted_ctr | ENUM | Expected CTR | | ad_group_criterion.effective_cpc_bid_micros | INT64 | Effective CPC bid | | ad_group_criterion.position_estimates.first_page_cpc_micros | INT64 | Estimated first page CPC |

Search Term Fields

| Field | Type | Description | |-------|------|-------------| | search_term_view.search_term | STRING | Actual user search query | | `search_term_view.status