query_events_aggregated

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. For ad-spend / ROAS metrics use 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:

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.

Get Started

Connecting Clients

Tools

Resources

Prompts

When to use

Parameters

Output

​When to use

​Parameters

​Output

When to use

Parameters

Output