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

Copy code
/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__mcp__Google_Ads__tool_execute_gaql to run queries directly and mcp__cogny__mcp__Google_Ads__tool_get_gaql_doc or mcp__cogny__mcp__Google_Ads__tool_get_reporting_view_doc for API documentation lookups.

Run it live

If Cogny isn't connected, skip this and note what connecting adds.

Syntax

Formal Grammar

Copy code
query         = SELECT field_list FROM resource_name
                [ WHERE condition_list ]
                [ ORDER BY ordering { , ordering } ]
                [ LIMIT positive_integer ]
                [ PARAMETERS param_list ]

field_list    = field_name { , field_name }
condition_list = condition { AND condition }
condition     = field_name operator value
ordering      = field_name [ ASC | DESC ]
param_list    = param_name = param_value { , param_name = param_value }

Clauses

Example

sqlCopy code
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

sqlCopy code
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)

sqlCopy code
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

sqlCopy code
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

sqlCopy code
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

sqlCopy code
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

sqlCopy code
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)

sqlCopy code
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:

sqlCopy code
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

sqlCopy code
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

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

segments.conversion_action_name (and the other conversion-action segments) can't be combined with cost metrics: metrics.cost_per_conversion or metrics.cost_micros fails with PROHIBITED_SEGMENT_WITH_METRIC_IN_SELECT_OR_WHERE_CLAUSE. For cost per conversion by action, run a second query without the segment for metrics.cost_micros, then divide client-side. Filtering on all_conversions keeps secondary (non-primary) actions, which report 0 in metrics.conversions.

Change History Audit

sqlCopy code
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):

Copy code
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, DEMAND_GEN (formerly DISCOVERY, which is no longer a valid enum and fails with BAD_ENUM_CONSTANT)
• KeywordMatchType: BROAD, PHRASE, EXACT
• BiddingStrategyType: TARGET_CPA, TARGET_ROAS, MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE, MANUAL_CPC, TARGET_IMPRESSION_SHARE; ENHANCED_CPC is deprecated (no longer available for Search and Display since March 2025) but can still appear on old campaigns
• Device: DESKTOP, MOBILE, TABLET, CONNECTED_TV, OTHER
• QualityScoreBucket: BELOW_AVERAGE, AVERAGE, ABOVE_AVERAGE

Rate Limits

Daily operations per developer token (access levels, rolling 24 hours):

• Explorer access: 2,880 operations/day on production accounts.
• Basic access: 15,000 operations/day.
• Standard access: unlimited operations/day.
• Short-term rate limits (RESOURCE_EXHAUSTED) still apply at every level; back off and retry.
• 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: Returned by default (unlike the UI, the API doesn't hide them). Add WHERE campaign.status != 'REMOVED' (or the resource's own status) to match the UI.
• 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/v25/overview_query_builder
• Resource Reference: https://developers.google.com/google-ads/api/fields/v25/overview (v25 is current as of 2026-10; swap in the latest version from https://developers.google.com/google-ads/api/docs/release-notes)
• Rate Limits: https://developers.google.com/google-ads/api/docs/best-practices/rate-limits
• Full Cogny Docs: https://cogny.com/docs/gaql-reference