Skip to main content

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.

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:
ParameterTypeRequiredDescription
group_bystring[]YesAt least one dimension to break down by.
order_bystringNoMetric slug to rank by. Defaults to the first metric in metrics.
order_dirstringNoasc or desc. Default: desc.
limitintegerNoTop-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
...