> ## 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_events_aggregated

> Aggregated count / sum / group-by over conversion events, without hydrating individual event rows.

A wrapper around `query_ad_metrics` that pre-filters to conversion metrics (counts + amounts) and curates the `group_by` surface to "time + source" type dimensions agents actually want here.

## When to use

* "Daily purchase count last 30 days."
* "Sum of revenue by ad source last week."
* Any question that wants a TOTAL or BUCKET, not individual rows.

For per-event rows use [`list_events`](/mcp/tools/list-events). For ad-spend / ROAS metrics use [`query_ad_metrics`](/mcp/tools/query-ad-metrics) directly.

## Parameters

| Parameter                 | Type      | Required    | Description                                                                                                                                                                                                  |
| ------------------------- | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `date_range`              | string    | Yes         | DateRange preset.                                                                                                                                                                                            |
| `attribution_model`       | string    | Yes         |                                                                                                                                                                                                              |
| `attribution_window`      | integer   | Yes         |                                                                                                                                                                                                              |
| `attribution_window_type` | string    | Yes         | `relative` or `absolute`.                                                                                                                                                                                    |
| `event_names`             | string\[] | Yes         | Event slugs OR human labels. Both work — the LabelResolver normalizes.                                                                                                                                       |
| `group_by`                | string\[] | No          | Bucketing dimensions. Default: `["day"]`. Valid: `day`, `week`, `month`, `quarter`, `year`, `sources`, `country`, `state`, `city`, `device_type`, `browser`, `os`, `campaign_name`, `adset_name`, `ad_name`. |
| `date_start` / `date_end` | string    | Conditional | When `date_range=custom`.                                                                                                                                                                                    |
| `sources`                 | string\[] | No          | Restrict to traffic sources.                                                                                                                                                                                 |
| `filters`                 | object    | No          | Same filter shape as `query_ad_metrics`.                                                                                                                                                                     |
| `format`                  | string    | No          | `csv` (default), `json`, or `yaml`.                                                                                                                                                                          |

## Output

CSV with `<group_by columns>, <event_count>, <event_amount>` rows:

```csv theme={null}
day,Deal Created,Deal Created_amount,purchase,purchase_amount
2026-05-08,12,4200,87,8240
2026-05-09,15,5300,92,8830
```

`# label_map: custom_event_2=Deal Created` appears in the footer when custom events were used.