> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cometly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# query_metric_breakdown

> Top-N ranked drill-down across one or more dimensions.

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:

```csv theme={null}
_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
...
```