The short answer
GAQL is the Google Ads Query Language. It lets you retrieve specific account resources, attributes, metrics and segments when a standard report does not answer the exact question you have.
AI makes GAQL much more approachable, but the safe workflow is not “ask a question and trust the table.” Ask the assistant to define the report grain, draft the query, show it to you, then run it only after you review the selected fields, date range, filters, segments and row limit.
Use a dedicated Google Ads report when one already matches the job. Use custom GAQL when you need an uncommon field, resource, filter or breakdown that the packaged report does not expose.
Table of Contents
What GAQL is good for
Combining account structure and performance fields in one report.
Filtering to a precise campaign type, status, label, date window or threshold.
Adding an uncommon segment such as device, network or conversion action.
Retrieving configuration details that are not part of a standard performance export.
Creating a repeatable query for an agency review, investigation or handoff.
GAQL is a reporting language, not a spreadsheet formula language and not a mutation language. A query retrieves Google Ads data. Changes to campaigns, budgets, ads or targeting happen through separate actions.
Start with the business question, not the query
A useful GAQL request states what decision the report should support. “Give me campaign data” is too vague. “Compare campaign spend and conversions by device for the last 30 days, excluding removed campaigns” defines the grain, time window, filters and metrics.
Before asking AI to draft a query, write down five things:
Decision: What will you do differently after reading the report?
Grain: What should one row represent - campaign, ad group, keyword, search term, asset or another resource?
Metrics: Which numbers answer the question?
Segments: Do you need a breakdown by day, device, network or conversion action?
Scope: Which account, campaigns and date range should be included?
That short specification prevents the model from solving a different reporting problem than the one you intended.
How a GAQL query is structured
A GAQL query uses six clauses in this order:
SELECT chooses the resource fields, metrics and segments returned.
FROM chooses one primary resource. That resource determines the report grain and which other fields are compatible.
WHERE filters the result set.
ORDER BY controls result order.
LIMIT caps the number of returned rows.
PARAMETERS changes supported response behavior.
SELECT and FROM are required. The other clauses are optional, but performance queries should normally have a finite date filter and a sensible limit.
A reviewable campaign-by-device query
The following example returns one row per campaign-device combination for the last 30 days:
The important phrase is “campaign-device combination.” Adding segments.device changes the row grain. If you compare these rows as if each campaign appeared once, or join them to another campaign-level table without aggregating first, your totals can be wrong.
A six-step AI workflow for custom Google Ads reports
1. Ask for a report plan before a query
Prompt:
I need to understand whether device mix explains the performance gap between campaigns.
Before writing GAQL, define the primary resource, intended row grain, fields, segments, filters and date range.
Flag anything that could split or suppress rows.This makes the assistant expose its assumptions before syntax distracts from the reporting logic.
2. Ask AI to draft GAQL using current field metadata
Prompt:
Draft a GAQL query for that plan.
Use only selectable, mutually compatible fields for the chosen FROM resource.
Include a finite date filter, ORDER BY, LIMIT and PARAMETERS omit_unselected_resource_names = true.
Do not run it yet.A plausible field name is not necessarily a valid field. Google’s field metadata controls whether a field is selectable, filterable, sortable and compatible with the rest of the query.
3. Review the query before execution
Check:
The FROM resource matches the intended row grain.
Every requested metric and segment is compatible with that resource.
The date window is explicit when metrics are selected.
Status and account-scope filters are intentional.
ORDER BY matches the question, rather than a convenient default.
LIMIT is large enough to avoid hiding relevant rows but small enough to review.
No segment was added merely because it was available.
4. Run a small preview
Start with a modest limit and inspect the first rows. Confirm column names, units, status values and row grain. A preview is not evidence that the totals are right, but it catches obvious scope and shape errors before a large export.
5. Export only after the shape is correct
For a large result, use CSV after the preview passes. Keep the query beside the export so another practitioner can reproduce the report and understand exactly how the rows were produced.
6. Reconcile one total
Choose one known campaign, date window or metric and compare the GAQL result with the Google Ads interface or a trusted dedicated report. If the numbers differ, investigate row grain, attribution settings, date boundaries, time zone, conversion columns and segmentation before drawing conclusions.
Copyable prompts for common GAQL jobs
Find the fields before writing the query
I want one row per [RESOURCE] with [FIELDS/METRICS] for [DATE RANGE].
Identify the correct FROM resource and verify that every requested field is selectable together.
If any field is incompatible, explain the closest valid alternative.
Do not run anything.Build a controlled performance cut
Draft a read-only GAQL SELECT query that answers: [BUSINESS QUESTION].
Scope it to [ACCOUNT/CAMPAIGNS], use [DATE RANGE], exclude removed entities, sort by [METRIC], and cap the result at [LIMIT].
Show the query and explain the row grain before running it.Diagnose an unexpected total
Review this GAQL query and result shape.
Identify every explicit and implicit segment, explain what one row represents, and show how I should aggregate the rows to compare them with a campaign-level total.
Do not change the query until you explain the mismatch.Turn a one-off report into a reusable template
Rewrite this validated GAQL query as a reusable template.
Mark the account, date range, campaign filters and limit as variables.
Add a one-sentence purpose, expected row grain and validation check.The mistakes that matter most
Choosing the wrong FROM resource
The FROM resource is not just a table name. It establishes the primary resource and implicitly segments the report at that level. Start from the entity that should define one row.
Adding too many segments
Every additional segment can multiply the number of rows. A campaign report segmented by device and date is no longer one row per campaign. Add only the dimensions needed for the decision.
Assuming all fields work together
Google restricts fields by resource and compatibility. Two valid field names can still be invalid in the same query. Have the assistant verify selectable_with relationships or use Google’s current field reference before execution.
Selecting a core date segment without a finite range
If segments.date, segments.week, segments.month, segments.quarter or segments.year appears in SELECT, Google requires a finite date range in WHERE. Since Jun 1, 2026, granular date and week reporting in current API versions is limited to a 37-month lookback; use month, quarter or year for older history.
Treating missing rows as zeros
Segmented reports omit rows where all selected metrics are zero. A missing day or device row does not automatically mean the entity disappeared, and zero-heavy inventory reports may need a separate configuration query.
Forgetting units and definitions
Cost is commonly returned in micros, so 1,000,000 micros equals one unit of account currency. Conversion and conversion-value fields also depend on the selected metric and the account’s conversion setup. State the exact field names when handing off analysis.
Letting AI execute an unreviewed query
GAQL is read-only, but a bad query can still waste time, omit important entities or produce a persuasive wrong conclusion. Treat query approval like a report-definition review, not a technical formality.
How HireOtto makes custom GAQL practical
HireOtto already includes dedicated Google Ads reports for common campaign, ad group, keyword, search term, impression share, conversion, asset and Performance Max workflows. Start there when the report matches your question: the output is more predictable and the assistant has fewer ways to misunderstand the grain.
For an edge case, an Agency-plan user can ask the assistant to draft a custom GAQL query, review the full SELECT statement, and then run it through HireOtto’s reporting action. HireOtto accepts read-only SELECT queries only, applies a finite row cap, and returns the fields explicitly selected in the query. You can request a short inline preview, a preview plus CSV, or CSV only; download links expire after 30 minutes by default.
The human gate remains important. HireOtto does not make incompatible fields compatible, validate the business meaning of the report, or decide whether a segmented total should be re-aggregated. Review the query before it runs and reconcile at least one result before acting on it.
Read the HireOtto reporting guide, check the Google Ads MCP tools reference for current GAQL availability and limits, then follow the HireOtto quickstart to connect your account.
Frequently asked questions
Is GAQL the same as SQL?
No. GAQL looks SQL-like, but it follows Google Ads resources, fields, compatibility rules and grammar. It does not support arbitrary joins, GROUP BY or data mutation.
Can GAQL change my campaigns?
No. GAQL retrieves data. Campaign changes use separate Google Ads API mutation actions. HireOtto’s custom GAQL path rejects non-SELECT queries.
Should I use GAQL for every report?
No. Use a dedicated report for routine campaign, keyword, search term, impression share, asset or PMax analysis. Use GAQL when the dedicated action lacks a field, resource, filter or segment you genuinely need.
Why does adding a segment change my totals?
A segment splits each primary-resource row into combinations. Device creates one row per resource-device combination; device plus date can create many rows per resource. Aggregate back to the intended comparison level before joining or ranking.
Why did Google Ads reject a field that exists in the documentation?
The field may not be selectable for your FROM resource, may be incompatible with another metric or segment, or may belong to a different API version. Recheck the current field metadata and simplify the query until the incompatible pair is isolated.
Can I export a custom GAQL report from HireOtto?
Yes. HireOtto supports inline summaries and CSV output for custom GAQL. The current product caps a run at 50,000 rows, and CSV download links expire after 30 minutes by default. Use a narrower scope or multiple intentional queries when the report exceeds the cap.
About Me
I’m Suyash – badminton junkie, ex‑GroupM ad‑ops grunt, first marketer at a B2B SaaS startup, and creator of Hiretto: Google Ads MCP Server.
My mission: less clicking, more thinking.
Let’s build leverage together.