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.
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 and gender.”
- “Which countries drove the most purchases in the last 30 days?”
- “Compare Facebook and Instagram results for the Spring Launch campaign.”
Related tools
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.
Last updated on