GAQL, Explained: Query Google Ads in Plain English (No Code)

If you have ever tried to get a specific report out of Google Ads, you may have run into GAQL. It stands for Google Ads Query Language, and it is the structured, SQL-like language the Google Ads API uses to fetch data. Want last week's spend by campaign, sorted high to low, with cost per conversion attached? In the raw API, you write a query for that.

Here is the good news. With Xylo, you never write GAQL. You connect your Google Ads account once, point your AI assistant at Xylo, and then just ask in plain English. The agent figures out the query, runs it, converts the numbers into readable dollars, and hands you back the answer.

This post explains what GAQL is and why it used to be a headache, shows you the plain-English questions to ask instead, and keeps a short reference at the end for developers who are curious about what is happening under the hood.

The short version: just ask

Xylo is a connector (an MCP server for Google Ads) that lets Claude, ChatGPT, Cursor, and other AI assistants work directly inside your Meta, Google, and TikTok ad accounts. Instead of writing a query, you type a sentence and your agent does the rest.

A few examples of what that looks like for Google Ads:

Show me my Google campaigns from the last 30 days, sorted by spend, and flag any whose cost per conversion is climbing.

Pull the search terms report for the last 7 days and list queries I should add as negative keywords.

Which keywords spent the most last week, and what is their quality score?

No SELECT, no FROM, no WHERE. No dividing numbers by a million. You ask, the agent answers.

What GAQL actually is (and why it was painful)

Most REST APIs let you ask for data by adding a few parameters to a URL. The Google Ads API works differently. You have to write a structured query that spells out exactly which resource you want, which fields to return, how to filter them, and how to sort. It looks a lot like SQL.

That design is powerful, but it comes with a learning curve and a handful of traps that have frustrated marketers and developers for years:

Money is in "micros." Google returns every dollar amount multiplied by a million. A cost of 15,234,560 actually means $15.23. Forget to divide and your report is off by six zeros.
Everything is an exact code. Statuses, campaign types, and match types are fixed enum values like ENABLED or EXACT. Get the spelling or casing wrong and the query fails.
No joins, no top-level OR. You cannot combine resources in one query, and there is no simple OR across conditions. Anything beyond a basic filter means running several queries and stitching the results together yourself.
Strict pairing rules. Certain fields and date breakdowns only work with certain resources, and if you filter by date you also have to return the date. Break a rule and you get an error instead of data.

None of this tells you anything about your ads. It is just plumbing. And it is exactly the kind of plumbing Xylo handles so you do not have to.

With Xylo plus your AI agent, you never touch any of it. You ask a question, and the micros, enums, and pairing rules are all handled behind the scenes.

What to ask instead of writing a query

Here is the same set of common Google Ads reports, mapped from "the thing you would have written in GAQL" to "the sentence you type to your agent."

What you want	What you ask your agent
Last 30 days of campaign performance, top spenders first	"Show me Google campaign performance for the last 30 days, sorted by spend."
Only active campaigns	"Just include active campaigns."
Sort by spend, then by conversions	"Sort by spend, and break ties by conversions."
Limit to the top 25	"Give me the top 25."

You can stack these naturally in one message, the way you would brief a teammate. "Show me my active Google campaigns for the last 30 days, sorted by spend, top 25, and call out anything with a cost per conversion above $40."

Campaign performance

How did my Google campaigns do over the last 30 days? Spend, clicks, conversions, and cost per conversion, sorted by spend.

The agent pulls the figures, converts micros to plain dollars, and turns status codes into readable words. You get a clean table without ever seeing a cost_micros.

Ad group performance

List my active Google ad groups from the last 7 days, sorted by conversions, top 50.

Keyword performance

Which Google keywords spent the most last week, and what is their quality score? Show clicks and conversions too.

Search terms report

The search terms report shows the actual phrases people typed that triggered your ads. It is one of the best places to find waste and new opportunities.

Pull the Google search terms report for the last 7 days, only terms with more than 10 impressions, and flag the ones I should add as negatives.

Daily breakdown

Give me a day-by-day spend and conversion breakdown for my Google campaigns in March.

Geographic and segment breakdowns

GAQL calls these "segments." You do not need the word. Just describe the cut you want.

Where are my Google conversions coming from by country over the last 30 days?

Break down last week's Google spend by device.

Which hours of the day convert best for me?

Your agent picks the right resource and segment, including the trickier ones like hour-of-day, and returns the breakdown.

One report across all three platforms

GAQL only covers Google. Most advertisers also run Meta and TikTok, and each platform has its own data format and its own quirks. Reconciling them by hand is a chore.

Xylo normalizes all three into one shape, so your agent can build a true cross-platform report from a single request.

Build me one report for last month covering Meta, Google, and TikTok: spend, conversions, and cost per result per platform, plus a combined total.

Same units, same column names, one answer. For a deeper look at this, see the cross-platform reporting guide.

Safety is built in

Reporting is read-only, but your agent can also make changes when you ask. Two things keep that safe:

New campaigns are created paused. Nothing starts spending until you review it and turn it on yourself.
Your credentials stay hidden. When you connect Google Ads, your tokens are encrypted (AES-256) and stored on Xylo's side. The AI agent never sees them. It works through Xylo's tools, not your raw account access.

For developers: a slim GAQL reference

If you are integrating directly or you just want to understand what the agent is doing, here is the short version. Most readers can skip this.

A GAQL query has the same skeleton every time:

SELECT field1, field2
FROM resource
WHERE condition
ORDER BY field DESC
LIMIT 100

A real example, last 30 days of campaign spend, active campaigns only, highest spenders first:

SELECT campaign.name, metrics.cost_micros, metrics.conversions
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_30_DAYS
ORDER BY metrics.cost_micros DESC

Common resources you query FROM include campaign, ad_group, ad_group_ad, keyword_view, search_term_view, and geographic_view. Date filters accept predefined ranges like LAST_7_DAYS and LAST_30_DAYS, or a custom BETWEEN '2026-01-01' AND '2026-03-31'. Remember that money fields end in _micros (divide by 1,000,000), statuses are exact enums, and if you filter on segments.date you must also select it.

Xylo's REST API skips the query writing entirely. You pass plain query parameters and get back normalized JSON with dollars instead of micros and readable statuses instead of enum codes. To pull campaign-level performance for the last 30 days:

curl "https://api.xylomcp.com/v1/google/insights?level=campaign&date_from=2026-02-03&date_to=2026-03-05" \
  -H "x-api-key: xy_sk_..." \
  -H "x-google-customer-id: 1234567890"

The base URL is https://api.xylomcp.com. Google endpoints live under /v1/google/... and need your x-google-customer-id header alongside your API key. You set the window with date_from and date_to, and you can switch level to ad_group or ad for finer detail. Responses follow the same { data, meta, paging? } shape as Meta and TikTok, so the cross-platform reporting above works out of the box. Under the hood, Xylo talks to Google Ads API v23. Full details are in the API documentation, and the Google Ads API getting started guide covers authentication setup.

Skip the query language

GAQL is a real skill, and it is worth knowing if you live in the raw Google Ads API. But for getting answers about your campaigns, you do not need it anymore.

Connect Xylo to your AI assistant, ask your questions in plain English, and let the agent handle the micros, the enums, and the syntax. It works with Claude, ChatGPT, Cursor, and anything else that speaks MCP, using the endpoint https://xylomcp.com/api/mcp.

The free tier is genuinely free: no credit card, one Google Ads account (plus one Meta and one TikTok), and the full set of 300+ ad operations across all three platforms. Sign up here, connect your account, and ask your first question. If you want ideas for what to try, browse our example prompts.