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

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

Ad Groups & Ads

Performance Views

Conversion & Attribution

Account & Extensions

Change History

Common Fields

Campaign Fields

Ad Group Fields

Ad Fields

Keyword & Criterion Fields

Search Term Fields

Metrics

Segments

WHERE Clause Operators

Comparison Operators

Set Operators

String Operators

Null Checks

Range Operators

Date Macros (DURING)

Common Query Patterns

Campaign Performance Report

SELECT
  campaign.id,
  campaign.name,
  campaign.status,
  campaign.advertising_channel_type,
  campaign.bidding_strategy_type,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value,
  metrics.cost_per_conversion
FROM campaign
WHERE campaign.status != 'REMOVED'
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC

Search Terms Report (Negative Keyword Identification)

SELECT
  search_term_view.search_term,
  search_term_view.status,
  segments.keyword.info.text,
  segments.keyword.info.match_type,
  campaign.name,
  ad_group.name,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions,
  metrics.cost_per_conversion
FROM search_term_view
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
  AND metrics.impressions > 10
ORDER BY metrics.cost_micros DESC
LIMIT 1000

Filter for high-cost, zero-conversion terms to build negative keyword lists.

Quality Score Analysis

SELECT
  campaign.name,
  ad_group.name,
  ad_group_criterion.keyword.text,
  ad_group_criterion.keyword.match_type,
  ad_group_criterion.quality_info.quality_score,
  ad_group_criterion.quality_info.creative_quality_score,
  ad_group_criterion.quality_info.post_click_quality_score,
  ad_group_criterion.quality_info.search_predicted_ctr,
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions
FROM keyword_view
WHERE campaign.status = 'ENABLED'
  AND ad_group.status = 'ENABLED'
  AND ad_group_criterion.status = 'ENABLED'
  AND ad_group_criterion.quality_info.quality_score IS NOT NULL
  AND segments.date DURING LAST_30_DAYS
ORDER BY ad_group_criterion.quality_info.quality_score ASC

Landing Page Performance

SELECT
  landing_page_view.unexpanded_final_url,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions,
  metrics.cost_per_conversion
FROM landing_page_view
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
  AND metrics.clicks > 0
ORDER BY metrics.clicks DESC
LIMIT 100

Device Breakdown

SELECT
  campaign.name,
  segments.device,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions,
  metrics.cost_per_conversion
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
ORDER BY campaign.name, segments.device

Geographic Performance

SELECT
  geographic_view.country_criterion_id,
  geographic_view.location_type,
  campaign.name,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value,
  metrics.cost_per_conversion
FROM geographic_view
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
  AND metrics.impressions > 0
ORDER BY metrics.cost_micros DESC
LIMIT 200

Ad Copy Performance (RSA Asset-Level)

SELECT
  campaign.name,
  ad_group.name,
  ad_group_ad.ad.id,
  ad_group_ad.ad.responsive_search_ad.headlines,
  ad_group_ad.ad.responsive_search_ad.descriptions,
  ad_group_ad.ad.final_urls,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions
FROM ad_group_ad
WHERE campaign.status = 'ENABLED'
  AND ad_group.status = 'ENABLED'
  AND ad_group_ad.status = 'ENABLED'
  AND ad_group_ad.ad.type = 'RESPONSIVE_SEARCH_AD'
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.impressions DESC

Asset-level performance:

SELECT
  campaign.name,
  ad_group.name,
  ad_group_ad_asset_view.field_type,
  ad_group_ad_asset_view.performance_label,
  asset.text_asset.text,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.cost_micros,
  metrics.conversions
FROM ad_group_ad_asset_view
WHERE campaign.status = 'ENABLED'
  AND ad_group.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
ORDER BY ad_group_ad_asset_view.performance_label DESC, metrics.impressions DESC

Budget Utilization / Impression Share

SELECT
  campaign.name,
  campaign.campaign_budget,
  campaign_budget.amount_micros,
  campaign.bidding_strategy_type,
  metrics.impressions,
  metrics.cost_micros,
  metrics.search_impression_share,
  metrics.search_top_impression_share,
  metrics.search_absolute_top_impression_share,
  metrics.search_budget_lost_impression_share,
  metrics.search_rank_lost_impression_share
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND campaign.advertising_channel_type = 'SEARCH'
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.search_budget_lost_impression_share DESC

Conversion Action Breakdown

SELECT
  campaign.name,
  segments.conversion_action_name,
  segments.conversion_action_category,
  metrics.conversions,
  metrics.conversions_value,
  metrics.all_conversions,
  metrics.all_conversions_value,
  metrics.cost_per_conversion
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
  AND metrics.conversions > 0
ORDER BY metrics.conversions DESC

Change History Audit

SELECT
  change_event.change_date_time,
  change_event.change_resource_type,
  change_event.change_resource_name,
  change_event.resource_change_operation,
  change_event.changed_fields,
  change_event.old_resource,
  change_event.new_resource,
  change_event.user_email
FROM change_event
WHERE change_event.change_date_time DURING LAST_14_DAYS
  AND change_event.change_resource_type IN (
    'CAMPAIGN', 'AD_GROUP', 'AD_GROUP_AD',
    'AD_GROUP_CRITERION', 'CAMPAIGN_BUDGET'
  )
ORDER BY change_event.change_date_time DESC
LIMIT 500

Gotchas and Important Notes

cost_micros Requires Division

All cost fields are in micros (1/1,000,000 of the currency unit):

Actual cost = metrics.cost_micros / 1,000,000
Actual CPC  = metrics.average_cpc / 1,000,000

Example: cost_micros = 5430000 means $5.43.

Segment + Metric Compatibility

• segments.conversion_action — impressions/clicks repeat across each conversion action row. Do not sum them.
• segments.click_type — clicks and impressions fragment by click type. Summing overcounts.
• segments.slot — only compatible with search campaigns.
• segments.hour — cannot be combined with segments.date for some resources.
• Check the Google Ads API field compatibility matrix when in doubt.

Date Range Requirements

• Queries with metrics.* fields require a date range (segments.date DURING ... or BETWEEN).
• Resource-only queries (no metrics) do not need a date range.

Enum Values

Enum fields must use string constant names:

• CampaignStatus: ENABLED, PAUSED, REMOVED
• AdGroupStatus: ENABLED, PAUSED, REMOVED
• AdvertisingChannelType: SEARCH, DISPLAY, SHOPPING, VIDEO, PERFORMANCE_MAX, MULTI_CHANNEL, LOCAL, SMART, HOTEL, DISCOVERY
• KeywordMatchType: BROAD, PHRASE, EXACT
• BiddingStrategyType: TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE, MANUAL_CPC, ENHANCED_CPC, TARGET_IMPRESSION_SHARE
• Device: DESKTOP, MOBILE, TABLET, CONNECTED_TV, OTHER
• QualityScoreBucket: BELOW_AVERAGE, AVERAGE, ABOVE_AVERAGE

Rate Limits

• Standard access: 15,000 requests/day, 1,600 operations/minute.
• Basic access: 10,000 requests/day.
• Use SearchStream for large result sets (one operation regardless of size).

Other Pitfalls

• No OR: All WHERE conditions are AND-joined. Use IN or separate queries.
• No joins: GAQL queries operate on a single resource.
• No GROUP BY: Aggregation is implicit by selected fields + segments.
• No aliases: Cannot use AS in GAQL.
• No arithmetic: Calculate cost_micros / 1000000 client-side.
• Segment auto-grouping: Adding a segment splits rows by that dimension.
• Removed resources: Excluded by default. Filter explicitly to include them.
• PARAMETERS clause: include_drafts = true for drafts, omit_unselected_resource_names = true to reduce response size.

Resources

• GAQL Grammar: https://developers.google.com/google-ads/api/docs/query/grammar
• Interactive Query Builder: https://developers.google.com/google-ads/api/fields/v17/overview_query_builder
• Resource Reference: https://developers.google.com/google-ads/api/fields/v17/overview
• Rate Limits: https://developers.google.com/google-ads/api/docs/best-practices/rate-limits
• Full Cogny Docs: https://cogny.com/docs/gaql-reference