> ## 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`](https://docs.cometly.com/mcp/tools/list-events). For ad-spend / ROAS metrics use [`query_ad_metrics`](https://docs.cometly.com/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.


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