> ## 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
...
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.