query_metric_breakdown

Same query plumbing as query_ad_metrics but with built-in sort + limit semantics. Optimized for “show me top 10 campaigns by ROAS” style questions where you want a ranked list, not a flat aggregate.

When to use

“Top 10 campaigns by ROAS last 7 days.”
“Worst 5 adsets by CPA this month.”
Any ranked list.

For period-over-period (query_ad_metrics_compare), multi-attribution (query_attribution_models), or single-row aggregates (query_ad_metrics), use those tools instead.

Parameters

Accepts every parameter query_ad_metrics does, plus:

Parameter	Type	Required	Description
`group_by`	string[]	Yes	At least one dimension to break down by.
`order_by`	string	No	Metric slug to rank by. Defaults to the first metric in `metrics`.
`order_dir`	string	No	`asc` or `desc`. Default: `desc`.
`limit`	integer	No	Top-N limit (1–100, default 10).

Output

CSV by default. Same shape as query_ad_metrics, with an added _rank column reflecting the requested ordering:

_rank,campaign_name,amount_spent,purchase,roas
1,Spring Launch,4820.50,142,4.92
2,Brand Search,2110.30,98,4.41
3,Retargeting,1955.80,73,3.74
...

Get Started

Connecting Clients

Tools

Resources

Prompts

When to use

Parameters

Output

​When to use

​Parameters

​Output

When to use

Parameters

Output