query_insights
Aggregate spend / impressions / clicks / conversions over a date range, by entity.
On this page
Reads the metrics that a provider reports for one advertiser, and adds them up over a date range. One call answers “what did this spend, and what did it return?” at any level: the whole account, one campaign, or every ad group side by side. Use list_advertisers first to get the advertiserId.
Input
| Field | Type | Required | Description |
|---|---|---|---|
advertiserId |
acc_* |
yes | The advertiser to read. It must belong to your organization. |
select |
string[] |
no | The metrics to compute. The default is ["spend", "impressions"]. |
breakdown |
string |
no | The level to group the rows by: provider, advertiser, or an entity type such as campaign, adset, ad_group, line_item, ad. Omit it to get one row for the whole range. |
interval |
'day' | 'week' | 'month' |
no | Group the rows into periods. Omit it to get one row for each group. |
relative |
'last_7_days' | 'last_15_days' | 'last_month' |
no | A relative date window. It has precedence over since and until. |
since |
string (YYYY-MM-DD) |
no | The first date to read, included. |
until |
string (YYYY-MM-DD) |
no | The last date to read, included. Use it with since. |
currency |
string (ISO 4217) |
no | Convert the money metrics into this currency before the sum. |
provider |
'meta' | 'gads' | 'tiktok' | 'snapchat' | 'dv360' |
no | Read one provider only. |
entityId |
string |
no | Read one entity only, by the bare id that its provider gives it. With an entity-type breakdown, it limits the breakdown to the subtree of that entity. |
entityType |
string |
no | Read one entity type only. AdCrunch ignores this field when breakdown is itself an entity type. |
limit |
number (1–100) |
no | The maximum number of rows. |
offset |
number |
no | The number of rows to skip. |
If you send no date range, AdCrunch reads the last 15 days.
Output
{ insights: [...] } — one row for each group.
Every row carries the metrics you asked for in select, and a currency. The currency is the account currency when each row in the group shares one, and null when the group mixes two or more.
The breakdown decides what else a row carries:
breakdown |
Each row also carries |
|---|---|
| omitted | nothing else — one row for the whole range |
provider |
provider |
advertiser |
provider, advertiserId |
| an entity type | provider, advertiserId, entityId, type |
An interval adds a date to each row. For a week, the date is the Monday. For a month, it is the first day.
Example
“How much did each Meta campaign spend last week, and what was the ROAS?”
Claude calls query_insights({ advertiserId: 'acc_123', breakdown: 'campaign', select: ['spend', 'roas'], relative: 'last_7_days' }) and reads back one row for each campaign. To see the trend day by day, it calls again with interval: 'day'.
Tip
Set a currency across ad accounts
A money metric comes back in the currency of its own ad account. If your
organization runs accounts in more than one currency, send currency — for
example currency: 'EUR' — so the totals are comparable. AdCrunch converts
each row at the European Central Bank rate of that row’s own date, and then
adds the rows up.
Warning
A metric is not available everywhere
Each provider reports a different set. The action_* funnel is Meta only.
Google Ads reports no reach, so reach, cpp and frequency read 0 there.
Do not compare those metrics across two providers.
Metrics
spend, clicks, impressions, ctr, cpc, cpm, cpp, cpa, roas, reach, frequency, conversions, conversion_value, action_add_to_cart, action_add_to_cart_value, action_purchase, action_purchase_value, action_initiate_checkout, action_initiate_checkout_value.
Errors
- Empty
insights— your organization does not own that advertiser, or the advertiser reports no data for that range. 401 Unauthorized— the OAuth token has expired. Authorize AdCrunch again from the settings of your AI client.