---
title: query_insights
description: Aggregate spend / impressions / clicks / conversions over a date range, by entity.
---

import Callout from '#docs/components/mdx/callout.astro';

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`](/mcp/tools/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'`.

> **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.

> **A metric is not available everywhere**
>
> Each provider reports a different set, and a metric a provider does not report
> reads `0` rather than `null`. [What each provider
> supports](/use/connect/providers#read-insights) has the full matrix — read it
> before you compare one metric 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` or `403` — see [Errors](/mcp/errors), which every tool shares. This one needs `observe:read`.