Google Ads: run a report (GAQL)
searchRead-onlyIdempotent
Reads rows from one Google Ads resource.
The tool writes the GAQL query from these parameters:
SELECT `fields` FROM `resource` WHERE `conditions` (joined with AND)
ORDER BY `orderings` LIMIT `limit`.
Args:
customer_id: The customer ID, digits only (123-456-7890 is
1234567890).
fields: The fields to return, each written in full, e.g.
"campaign.id".
resource: The one resource the rows come from, e.g. "campaign".
conditions: Filters, one GAQL condition each, e.g.
"campaign.id = 123"; every one must hold.
orderings: Sort order, e.g. "metrics.clicks DESC".
limit: The maximum number of rows to return.
start_date: Report start date (YYYY-MM-DD). Adds a quoted `segments.date`
filter — use this instead of hand-writing dates into `conditions`.
On change_event/change_status it filters their own date-time.
end_date: Report end date (YYYY-MM-DD). Combined with start_date this
produces a finite `segments.date BETWEEN 'start' AND 'end'` filter
(on change_event/change_status, a range on their own date-time
instead).There is no parameter for a whole query string, and a parameter not listed above is refused rather than ignored.
Example
The enabled ads of one campaign, by ad group:
resource="ad_group_ad"
fields=["ad_group.name", "ad_group_ad.ad.id", "ad_group_ad.status"]
conditions=["campaign.id = 12345678901",
"ad_group_ad.status = 'ENABLED'"]
orderings=["ad_group.name"]
Clicks and cost by campaign for August:
resource="campaign"
fields=["campaign.name", "metrics.clicks", "metrics.cost_micros"]
start_date="2026-08-01", end_date="2026-08-31"GAQL reference, for writing fields and conditions
Overview: https://developers.google.com/google-ads/api/docs/query/overview
Language Grammar: https://developers.google.com/google-ads/api/docs/query/grammar
Resources and fields: https://developers.google.com/google-ads/api/fields/v23/overview
get_resource_metadata returns the fields a resource can select, filter
and sort by, and the list of valid resources when the name given is not
one. Field names are written in full ('campaign.id', not 'id'); wildcards
and partial field names are not accepted. Common resources: campaign,
ad_group, ad_group_ad, ad_group_criterion, keyword_view,
search_term_view, campaign_budget, customer, asset, change_event.Dates
start_date and end_date (YYYY-MM-DD) add a correctly quoted
`segments.date` filter (change_event and change_status are the
exception, see below), which avoids the most common query error. A date
written into `conditions` is a quoted string, e.g.
segments.date BETWEEN '2026-08-01' AND '2026-08-28' (an unquoted date is
a GAQL syntax error). Date literals from the Grammar (e.g. DURING
LAST_7_DAYS) are not supported here.Keyword and search-term reporting
Metrics on keyword_view and search_term_view are attributed only to the
matched keyword/term, so they will NOT sum to the campaign or ad_group
totals. The remainder is traffic with no single matched keyword, plus
low-volume search terms Google withholds below a privacy threshold. This
is expected Google attribution, NOT a data error; top-line numbers
reconcile at the campaign or ad level.change_event and change_status
Pass start_date AND end_date plus a limit of at most 10000. The dates
filter change_event.change_date_time / change_status.last_change_date_time
(these resources forbid segments.date). Google keeps change_event for the
last 30 days and change_status for the last 90 days.Conversions
Upload issues: offline_conversion_upload_conversion_action_summary
(https://developers.google.com/google-ads/api/docs/conversions/upload-summaries).Tools revision: 5c9bea8f.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| fields | Yes | ||
| end_date | No | ||
| resource | Yes | ||
| orderings | No | ||
| conditions | No | ||
| start_date | No | ||
| customer_id | Yes |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |