query_insights

Aggregate spend / impressions / clicks / conversions over a date range, by entity.

Ask what an ad account spent and what it returned, for the full ad account or for each campaign, ad set or ad. The agent adds up the metrics that AdCrunch stores for the dates that you name.

How much did each Meta campaign spend last week, and what was the ROAS?

The agent reads the metrics of that week, with one row for each campaign. You see the spend and the return on ad spend of each campaign. Read your accounts shows the full job.

Reference

Available on:

Query advertising insights/metrics for an advertiser. Supports breakdown by provider, advertiser, or any native entity type (campaign, adset, ad_group, line_item, ad, …), time intervals (day/week/month), date ranges (since/until or a relative window like last_7_days), and metric selection (spend, impressions, clicks, ctr, cpm, roas, etc.). Defaults to spend + impressions over the last 15 days when no date range is provided. The rows come in order of the period, then the entity. The answer holds at most limit rows (default 100, maximum 500). When it carries nextCursor, more rows exist: call this tool again with the same arguments and cursor set to that value. When it carries no nextCursor, you have every row.

Input

Argument	Type	Required	Description
`advertiserId`	string	yes	Advertiser account ID (format: `acc_<id>`). Must belong to the active organization. Use list_advertisers to discover IDs.
`breakdown`	one of `provider`, `advertiser`, `campaign`, `adset`, `adgroup`, `ad_group`, `ad_group_ad`, `insertion_order`, `line_item`, `asset_group`, `keyword`, `audience`, `listing_group`, `ad`, `creative`	no	Group results by entity level. Allowed values are native provider entity types (campaign, adset, ad_group, line_item, ad, …) plus provider and advertiser. Omit to return a single fully aggregated row.
`currency`	string, 3 characters	no	Display currency (ISO 4217, e.g. `USD`). Converts monetary metrics (spend, conversion values, cpc, cpm, cpa) from each row’s account currency using the ECB reference rate of the row’s own date, before aggregation. Omit for unconverted account-currency values — rows are then annotated with their `currency`. Pass it whenever the organization has advertisers in more than one currency, otherwise totals silently mix currencies.
`entityId`	string	no	Filter to a single entity by its bare provider-native id, or combine with an entity-type `breakdown` to scope the breakdown to that entity’s subtree.
`entityType`	string	no	Filter rows to a single provider-native entity type (campaign, adset, ad_group, line_item, ad, …). IGNORED when `breakdown` is itself an entity type — in that case the breakdown defines the row grain. Applies only when there is no entity-type breakdown.
`interval`	one of `day`, `week`, `month`	no	Time bucket for time-series results: day, week, or month. Omit for an all-time aggregate over the date range.
`cursor`	string, at least 1 character	no	The `nextCursor` of the previous page. Omit it to get the first page. Send it with no change, and with the same filters as the request that answered it: a cursor from a different query gets a 400 `invalid_cursor`. Do not build or change a cursor.
`limit`	integer, 1 to 500	no	The greatest number of rows on the page, from 1 to 500. The default is 100. A greater value gets a 400, with `error` of `invalid_request`. Default: `100`.
`provider`	one of `meta`, `gads`, `tiktok`, `snapchat`, `dv360`	no	Filter results to a single ad provider (meta, gads, tiktok, snapchat, dv360).
`relative`	one of `last_15_days`, `last_month`, `last_7_days`	no	Relative date window. Allowed values: last_7_days, last_15_days, last_month. Takes precedence over `since`/`until`. Defaults to last_15_days when no date range is provided.
`select`	array of (one of `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`)	no	Metrics to compute. Defaults to [“spend”, “impressions”]. Allowed values: 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. Coverage differs by provider: the action_* funnel is Meta-only, and Google Ads reports no reach — so reach, cpp and frequency read 0 there. Do not compare those across providers.
`since`	string	no	Inclusive start date in YYYY-MM-DD format. Used together with `until` for a fixed range. Ignored when `relative` is set.
`until`	string	no	Inclusive end date in YYYY-MM-DD format. Used together with `since`. Ignored when `relative` is set.

Output

A successful call returns this object in structuredContent.

Field	Type	Always present	Description
`insights`	array of object	yes	One row for each group, in the order of the period, then of the entity. An empty array means that no data matches, or that the organization does not own the advertiser.
`insights[].advertiserId`	string	no	The advertiser of the row, prefixed `acc_`. Present when `breakdown` is `advertiser` or an entity type.
`insights[].currency`	string or null	yes	The ISO 4217 currency of the money in the row. With the `currency` argument, it is that currency on each row. With no `currency` argument, it is the currency of the ad account, and null when the rows of the group have two or more currencies.
`insights[].date`	string	no	The first day of the period, `YYYY-MM-DD`. Present only with `interval`. A week starts on its Monday, and a month on its first day.
`insights[].entityId`	string	no	The entity of the row, as the id that its provider gives it. Present when `breakdown` is an entity type.
`insights[].provider`	one of `meta`, `tiktok`, `snapchat`, `gads`, `dv360`, `x`, `openai`	no	The provider of the row: `meta`, `tiktok` or `gads`. Present when you send `breakdown`.
`insights[].type`	string	no	The provider type of `entityId`, such as `campaign`, `adset`, `adgroup` or `ad_group`. Present when `breakdown` is an entity type.
`insights[].action_add_to_cart`	number	no	Add-to-cart actions. Meta only: the other providers answer 0.
`insights[].action_add_to_cart_value`	number	no	The value of those add-to-cart actions, as money. Meta only.
`insights[].action_initiate_checkout`	number	no	Checkouts that started. Meta only: the other providers answer 0.
`insights[].action_initiate_checkout_value`	number	no	The value of those checkouts, as money. Meta only.
`insights[].action_purchase`	number	no	Purchases. Meta only: the other providers answer 0.
`insights[].action_purchase_value`	number	no	The value of those purchases, as money. Meta only.
`insights[].clicks`	number	no	Clicks.
`insights[].conversion_value`	number	no	The value of the conversions, as money.
`insights[].conversions`	number	no	Conversions, as the provider counts them.
`insights[].cpa`	number	no	Cost per conversion: spend ÷ conversions.
`insights[].cpc`	number	no	Cost per click: spend ÷ clicks.
`insights[].cpm`	number	no	Cost per thousand impressions: spend ÷ impressions × 1000.
`insights[].cpp`	number	no	Cost per thousand people reached: spend ÷ reach × 1000. Google Ads reports no reach, so it answers 0.
`insights[].ctr`	number	no	Click-through rate, as a percentage: clicks ÷ impressions × 100. A `ctr` of 1.5 is 1.5%.
`insights[].frequency`	number	no	Impressions ÷ reach. Google Ads reports no reach, so it answers 0.
`insights[].impressions`	number	no	Impressions.
`insights[].reach`	number	no	People reached. Google Ads does not report it, so it answers 0.
`insights[].roas`	number	no	Return on ad spend: conversion value ÷ spend.
`insights[].spend`	number	no	The money spent, in whole units of `currency`.
`nextCursor`	string	no	Send this value as `cursor` to get the next page. It is absent on the last page.

Failure codes

A failed call has isError set, and structuredContent.error holds one of these codes. Errors describes the shape of a failed call.

invalid_cursor
forbidden
invalid_request
internal_error

Scope

The token must hold observe:read. Auth & scopes lists each scope.

Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

Read-only. The tool changes nothing.
Closed world. The tool reads and writes the data of AdCrunch only.

Example

The arguments:

{
  "advertiserId": "acc_1203456789012345",
  "breakdown": "campaign",
  "relative": "last_7_days",
  "select": [
    "spend",
    "impressions",
    "clicks",
    "roas"
  ]
}

The result, in structuredContent:

{
  "insights": [
    {
      "advertiserId": "acc_1203456789012345",
      "clicks": 3180,
      "currency": "EUR",
      "entityId": "120210000000000001",
      "impressions": 212400,
      "provider": "meta",
      "roas": 3.42,
      "spend": 1284.5,
      "type": "campaign"
    },
    {
      "advertiserId": "acc_1203456789012345",
      "clicks": 1045,
      "currency": "EUR",
      "entityId": "120210000000000002",
      "impressions": 58900,
      "provider": "meta",
      "roas": 5.18,
      "spend": 612.75,
      "type": "campaign"
    }
  ]
}