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.

The agent names a level with the same word for every provider: campaigns, ad-groups, ads, creatives or asset-groups. Each row keeps the word of its provider, so an ad group reads adset on Meta and adgroup on TikTok. A provider that does not have the level gives no row: only Meta has creatives, and only Google Ads has asset groups.

Reference

Available on:

Query advertising insights/metrics for an advertiser. Supports breakdown by a concept (campaigns, ad-groups, ads, creatives, asset-groups), by provider or advertiser, or by a native entity type of one provider (campaign, adset, adgroup, ad_group, 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

Output

A successful call returns this object in structuredContent.

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": "campaigns",
  "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"
    }
  ]
}