Reports and GAQL: querying any Google Ads report from the chat

All reporting goes through one tool, consultar_relatorio, which runs a read-only GAQL query against the account you choose. GAQL is Google's SQL-like language: you pick a resource, the fields and metrics you want, a date range and filters.

What a query looks like

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

The assistant writes this for you from "show me spend, clicks and conversions by campaign for the last 30 days". Costs come back in micros (divide by 1,000,000); the assistant converts them.

Most useful resources

Resource	Use it for
`campaign`	Spend pacing, conversions, bid strategy, budget per campaign
`ad_group`	Performance by theme, CPCs, status
`keyword_view`	Keyword metrics, Quality Score, match types, zero-impression keywords
`search_term_view`	Actual queries that triggered ads: the source of negatives
`ad_group_ad`	Ad copy, approval status, ad strength, performance per ad
`asset`, `asset_group_asset`	Performance Max asset performance labels
`geographic_view`, `user_location_view`	Performance by location
`campaign` with `segments.device`, `segments.hour`, `segments.day_of_week`	Device and time breakdowns
`conversion_action`	Conversion setup audit
`change_event`	Who changed what, including PaidHelm's own changes
`campaign_budget`, `bidding_strategy`	Shared budgets and portfolio strategies
`recommendation`	Google's recommendations with their estimated impact

Date ranges

Named ranges: TODAY, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH, THIS_WEEK_SUN_TODAY, LAST_BUSINESS_WEEK. Or explicit: segments.date BETWEEN '2026-10-01' AND '2026-10-31'. Comparisons (this month vs last month) take two tasks, one per period, and the assistant computes the deltas.

Report prompts that work

Give me a weekly summary for last week vs the week before: spend, conversions, CPA and conversion rate by campaign, and highlight anything that moved more than 20%.

Show search terms from the last 14 days with more than 10 clicks and zero conversions, sorted by cost.

Which keywords have Quality Score 4 or below and spent more than $100 this month?

Break down last month's conversions by device and hour of day for the "Brand" campaign.

List all ads with approval status other than APPROVED and the reason.

What changed in this account in the last 7 days? Use change_event and group by user.

Limits

One query returns up to 10,000 rows; the assistant pages or narrows the filter when needed.
Some metrics cannot be combined with some segments (Google's rule); the assistant will adjust and tell you.
Manager accounts: metrics must be queried per client account. Ask for "all accounts" and the assistant loops, one task each.

Frequently asked questions

Do I need to know GAQL?

No. You ask in plain language and the assistant writes the query. Knowing a few field names helps when you want something unusual, and you can always ask the assistant to show the query it ran.

How far back can reports go?

Google Ads keeps most performance data for years; search terms and some asset reports are limited by Google to recent periods. Date ranges follow the API: specific dates or named ranges such as LAST_30_DAYS.

Can the assistant export to a spreadsheet?

Results come back as structured text that the assistant can format as a table, CSV or Markdown. In Claude and ChatGPT you can ask for a downloadable file; in Cursor or Claude Code it can write the CSV directly to your project.