query_insights
Aggregate spend / impressions / clicks / conversions over a date range, by entity.
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–500) |
no | The greatest number of rows in the answer. The default is 100. |
cursor |
string |
no | The nextCursor of the previous answer. Omit it to get the first page. |
If you send no date range, AdCrunch reads the last 15 days.
Output
{ insights: [...], nextCursor? } — one row for each group, in order of the period, then the entity. When nextCursor is present, more rows exist: call query_insights again with the same arguments and cursor set to that value.
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'.
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. invalid_cursor— thecursoris not anextCursorof this query. Send it with no change and with the same arguments, or omit it.401or403— see Errors, which every tool shares. This one needsobserve:read.