meta_ads_insights_breakdown
Retrieve ad delivery metrics (impressions, clicks, spend, conversions) for a campaign, segmented by audience dimensions like age, gender, country, or device platform. Ideal for ad-hoc performance analysis across specific breakdowns.
Instructions
Pulls delivery metrics for a campaign broken down along one dimension (age, gender, device_platform, placement, country, region, etc.). Returns rows with the breakdown key plus impressions, clicks, spend, cpc, ctr, conversions, and cost_per_conversion. Read-only. Use this for ad-hoc slicing; for pre-packaged splits use the dedicated meta_ads_analysis_audience (age/gender) or meta_ads_analysis_placements tools, which add interpretation.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| account_id | No | Meta Ads account ID in the format 'act_XXXXXXXXXX' (e.g. 'act_1234567890'). Optional — falls back to META_ADS_ACCOUNT_ID from the configured credentials. The leading 'act_' prefix is required. | |
| campaign_id | Yes | Campaign to break down. | |
| breakdown | No | Dimension to split by. Meta accepts a single breakdown or a small set joined by commas (e.g. 'age,gender'). Some combinations are rejected by Meta — stick to one breakdown per call when unsure. | |
| period | No | Analysis window. Accepts Meta predefined ranges ('today', 'yesterday', 'last_7d', 'last_14d', 'last_30d' (default), 'last_90d') or explicit 'YYYY-MM-DD..YYYY-MM-DD'. Longer windows cost more Graph API quota. |