Get insights breakdown (`adsap_get_insights_breakdown`)

Platform: Meta · Read or write: Read · Plan: Early Access · Consumes a task: No · Preview supported: No

What it does

Slices spend and performance by age, gender, country, region, platform or placement. It calls Meta live for every request, so results are current but not cached. You can group the breakdown by campaign, ad set or ad and sort by any metric.

When to use it

Use it to split spend and performance by one dimension: age, gender, country, region, platform, position or device.
Each call takes exactly one value in breakdown_dimensions. For age and gender, the assistant makes two calls.
Every call reads Meta live and nothing is cached. Rows are totals for the whole date range, not one row per day.
results, cost_per_result and the three ranking metrics are not available here. For those, use adsap_get_insights.
summary adds up only the rows returned. Raise limit, up to 200, when you need every bucket in the total.

Worked example

You ask

“Which two age groups spent the most in the Spring sale campaign over the last 30 days?”

The assistant calls `adsap_get_insights_breakdown`


{
  "ad_account_id": "act_1234567890",
  "entity_type": "campaign",
  "entity_ids": ["120210000000002"],
  "breakdown_dimensions": ["age"],
  "date_preset": "last_30d",
  "metrics": ["spend", "link_clicks", "ctr", "purchase_roas"],
  "sort_by": "spend",
  "limit": 2
}

Adsap returns

The field names are the ones Adsap returns. The values are examples.


{
  "entity_type": "campaign",
  "breakdown_dimensions": ["age"],
  "date_range": { "from": "2026-08-19", "to": "2026-09-17" },
  "row_count": 2,
  "rows": [
    {
      "age": "25-34",
      "entity_name": "Spring sale",
      "spend": 1240.5,
      "link_clicks": 1473,
      "ctr": 1.5,
      "purchase_roas": 3.2
    },
    {
      "age": "35-44",
      "entity_name": "Spring sale",
      "spend": 860.25,
      "link_clicks": 858,
      "ctr": 1.2,
      "purchase_roas": 2.1
    }
  ],
  "summary": {
    "total_spend": 2100.75,
    "total_link_clicks": 2331,
    "ctr": 1.37,
    "purchase_roas": 2.75
  }
}

How to read it

Each row is one bucket of the dimension you asked for, here an age range, with the metrics you requested. ctr is the link click rate as a percentage, and purchase_roas is purchase value divided by spend. Rows also carry date_start and date_stop for the range.

summary totals the two rows shown, not the whole campaign, because the call set limit to 2. Its ctr and purchase_roas are worked out from the summed totals, not averaged across rows.

Parameters

Descriptions are shortened from the tool schema. Your assistant sees the full text.

Name	Type	Required	Description
`ad_account_id`	string	Yes	Must include act_ prefix.
`entity_type`	one of `account`, `campaign`, `adset`, `ad`	Yes
`entity_ids`	array of string	No	Filter to specific IDs.
`breakdown_dimensions`	array of one of `age`, `gender`, `region`, `country`, `publisher_platform`, `platform_position`, `device_platform`, `impression_device`	Yes	One or more dimensions to slice results by. Options: age (13-17, 18-24, 25-34, 35-44, 45-54, 55-64, 65+), gender (male/female/unknown), country (ISO codes), region… Max 2 dimensions recommended: Meta rejects some combinations.
`date_preset`	one of `today`, `yesterday`, `last_3d`, `last_7d`, `last_14d`, `last_30d`, `this_month`, `last_month`	No	Required if no date_from/date_to.
`date_from`	string	No	YYYY-MM-DD. Required if no date_preset.
`date_to`	string	No	YYYY-MM-DD. Required if no date_preset.
`group_by`	one of `campaign`, `adset`, `ad`	No	Secondary grouping by entity level.
`metrics`	array of string	No	Any of: spend, impressions, clicks, link_clicks, outbound_clicks, conversions, purchase_conversions, lead_conversions, add_to_cart_conversions, conversion_value, purchase_value, video_views (=75% completion), video_thruplay, video_p25, video_p50, video_p75, video_p95, video_p100… Defaults to spend, impressions, link_clicks, ctr, cpc, cpm, results, cost_per_result, purchase_roas.
`sort_by`	string	No
`sort_dir`	one of `asc`, `desc`	No
`limit`	number	No	Default 50, max 200.

Example prompts

“Break down last month’s spend by age.”
“Which countries drove the most purchases in the last 30 days?”
“Compare Facebook and Instagram results for the Spring Launch campaign.”

adsap_get_account_activities: Retrieve change log for a Meta ad account: budget changes, status toggles, ad creation/deletion, billing events, policy actions.
adsap_get_account_health: Full health check on a Meta ad account.
adsap_get_account_summary: Structural snapshot of a Meta ad account: campaign counts by status/objective, ad set counts, active ad count, budget allocation, top…
adsap_get_insights: Retrieve aggregated spend and performance metrics for accounts, campaigns, ad sets, or ads over a date range.
adsap_list_experiments: List an ad account’s Meta experiments / ad studies (live from Meta): A/B split tests and conversion-lift studies, with type, status…

Guide

Read Insights and reporting for the workflow around this tool, and the Tool reference for every tool.

The Meta Ads MCP server page shows how to connect Meta Ads to Claude, ChatGPT or Perplexity.

Get insights breakdown (adsap_get_insights_breakdown)