Google Ads Query Language (GAQL) Reference

Overview

Google Ads Query Language (GAQL) is the query language used by the Google Ads API to retrieve reporting data and resource metadata. It resembles SQL but operates on a fixed set of resource types rather than arbitrary tables. Understanding GAQL is essential for pulling performance data, auditing campaigns, and building automated optimizations with Cogny.

API endpoint: GoogleAdsService.SearchStream (streaming) or GoogleAdsService.Search (paged)

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

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

2. Search Terms Report (with 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

Use this to identify wasted spend: filter for search terms with high cost and zero conversions to build negative keyword lists.

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

4. 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,
  metrics.bounce_rate
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

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

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

7. Ad Copy Performance (RSA Asset-Level)

SELECT
  campaign.name,
  ad_group.name,
  ad_group_ad.ad.id,
  ad_group_ad.ad.type,
  ad_group_ad.ad.responsive_search_ad.headlines,
  ad_group_ad.ad.responsive_search_ad.descriptions,
  ad_group_ad.ad.final_urls,
  ad_group_ad.policy_summary.approval_status,
  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

For asset-level performance (which headline/description combinations performed best):

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

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

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

10. 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). Always divide by 1,000,000 for human-readable values:

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

For example, cost_micros = 5430000 means $5.43 (or 5.43 in the account's currency).

Segment + Metric Compatibility

Not all segments can be used with all metrics. Key rules:

• segments.conversion_action — when you add this segment, metrics.conversions and metrics.conversions_value break down by conversion action, but metrics.clicks and metrics.impressions will repeat across each conversion action row. Do not sum impressions/clicks when conversion segments are present.
• segments.click_type — similar issue; clicks and impressions fragment by click type. Summing them will overcount.
• segments.slot — only compatible with search campaigns.
• segments.hour — cannot be combined with segments.date in the same query for some resources. Use one or the other.
• Check the Google Ads API field compatibility matrix when in doubt.

Date Range Requirements

• Queries that include any metrics.* field require a date range via segments.date DURING ... or segments.date BETWEEN ... AND ....
• If you omit the date range, the API returns an error for metric-bearing queries.
• Resource-only queries (no metrics) do not need a date range.

Enum Values

Enum fields must use their string constant names. Common enum values:

CampaignStatus: ENABLED, PAUSED, REMOVED

AdGroupStatus: ENABLED, PAUSED, REMOVED

AdGroupAdStatus: 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, MANUAL_CPM, MANUAL_CPV

Device: DESKTOP, MOBILE, TABLET, CONNECTED_TV, OTHER

QualityScoreBucket: BELOW_AVERAGE, AVERAGE, ABOVE_AVERAGE

Rate Limits

• Standard access: 15,000 requests per day, 1,600 operations per minute per developer token.
• Basic access: 10,000 requests per day.
• Use SearchStream instead of Search for large result sets to avoid pagination overhead and reduce quota consumption.
• Each SearchStream call counts as one operation regardless of result size.
• Batch multiple queries in parallel where possible, but respect the per-minute operation limit.

Other Pitfalls

• No OR in WHERE: All conditions are AND-joined. To simulate OR, run separate queries or use IN.
• No joins: GAQL queries operate on a single resource. Use attributed resources (e.g., search_term_view already includes campaign and ad group fields).
• No GROUP BY: Aggregation is implicit. The API groups by the combination of resource fields and segments you select.
• No aliases: You cannot use AS in GAQL. Field names are returned as-is.
• No arithmetic: You cannot do metrics.cost_micros / 1000000 in GAQL. Perform calculations client-side.
• Segment auto-grouping: Adding a segment to SELECT automatically splits rows by that segment. Selecting segments.device means you get one row per campaign per device, not one row per campaign.
• Removed resources: By default, REMOVED entities are excluded. To include them, filter explicitly with campaign.status IN ('ENABLED', 'PAUSED', 'REMOVED').
• PARAMETERS clause: Use PARAMETERS include_drafts = true to include draft campaigns, or PARAMETERS omit_unselected_resource_names = true to reduce response size.

Next Steps

• Google Ads API Requirements - Connect your Google Ads data
• AI Report Generation - How Cogny analyzes ads data
• GA4 BigQuery Export Schema - Combine with GA4 analytics data

Claude Code Skill

This GAQL reference is also available as a free Claude Code skill -- use it directly in your terminal:

# Install
curl -sSL https://raw.githubusercontent.com/cognyai/claude-code-marketing-skills/main/install.sh | bash

# Use
/gaql-reference                           # 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

View on GitHub →

Resources

• GAQL Grammar Reference: developers.google.com/google-ads/api/docs/query/grammar
• GAQL Interactive Query Builder: developers.google.com/google-ads/api/fields/v17/overview_query_builder
• Google Ads API Resource Reference: developers.google.com/google-ads/api/fields/v17/overview
• Google Ads API Rate Limits: developers.google.com/google-ads/api/docs/best-practices/rate-limits
• Claude Code Marketing Skills: github.com/cognyai/claude-code-marketing-skills