Search terms are the words people actually typed, as opposed to the keywords you bought. The gap between the two is where most wasted spend lives, and reading it is one call that cannot change anything.
The call
curl -sG https://top-rated.team/google-ads/v1/accounts/1234567890/report \ -H "X-API-KEY: $MAKEHYBRID_KEY" \ --data-urlencode 'query=SELECT search_term_view.search_term, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM search_term_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.cost_micros DESC' \ --data-urlencode 'max_rows=200'
The query is Google Ads Query Language, and everything Google will report can be asked for this way: campaigns, ad groups, keywords, ads, assets, budgets, conversions, audiences, the change history. Up to 200 rows an answer.
Reading what comes back
- Cost is in micros: 1,000,000 micros is one unit of the account's currency. A term at 4,310,000 cost 4.31.
- A term with spend and no conversions over thirty days is the first thing to look at, and the usual answer is a negative keyword rather than a bid change.
- The GET takes the query in the URL; POST to the same address takes it in a body, for a query too long to fit. Both only read.
Nothing in this recipe can alter the account. A report is a read, and the call that changes something is a different one, with a person on the end of it.
Questions people ask
Do I need to know GAQL?
To write a query by hand, yes, and it is close enough to SQL to read without learning it. In practice an AI agent on this key writes the query from what you asked for in words, runs it, and reads you the rows.
Why micros?
It is how Google reports money, so it is how this answers: an integer of millionths, which avoids the rounding you would get passing fractions of a currency around. Divide by a million to get the amount a person would say.
Can a report touch the account?
No. The report call refuses anything that is not a SELECT, so there is no query you can put through it that alters an account — a mistake here costs you a confusing answer and nothing else.