Meta Ads Breakdowns
Breakdowns in the Meta Ads API let you segment statistics by various dimensions. With breakdowns, you can analyze ad performance by audience, platform, and time.
Types of Breakdowns
Demographic Breakdowns
Breakdowns by audience characteristics:
| Parameter | Description | Possible Values |
|---|---|---|
age | Age group | 13-17, 18-24, 25-34, 35-44, 45-54, 55-64, 65+ |
gender | Gender | male, female, unknown |
Geographic Breakdowns
Breakdowns by audience location:
| Parameter | Description | Note |
|---|---|---|
country | Country | Two-letter ISO 3166-1 code |
region | Region/area | Availability depends on the country |
dma | Designated market area | Primarily for the US |
city | City | May be unavailable for smaller cities |
Technical Breakdowns
Breakdowns by platform and device:
| Parameter | Description | Values |
|---|---|---|
publisher_platform | Platform | facebook, instagram, messenger, audience_network |
platform_position | Position on the platform | feed, story, reels, search, instream, marketplace |
device_platform | Device type | desktop, mobile, tablet, other |
impression_device | Impression device | android, ios, other |
Placement Breakdowns
Specific ad placement locations:
| Parameter | Description |
|---|---|
placement | Placement location |
product_id | Product identifier (for dynamic ads) |
Time-Based Breakdowns
| Parameter | Description |
|---|---|
hourly_stats_aggregated_by_advertiser_time_zone | Hourly statistics in the account's time zone |
hourly_stats_aggregated_by_audience_time_zone | Hourly statistics in the audience's time zone |
Combining Breakdowns
The API allows combining several breakdowns at once. Examples of useful combinations:
| Combination | Analytical Value |
|---|---|
age + gender | Demographic profile of the audience |
country + publisher_platform | Platform performance by country |
placement + device_platform | Which placements perform well on mobile |
age + gender + placement | Full audience profile by placement |
Combination limitations:
- Some breakdowns are incompatible with each other
- It's recommended to use no more than 2-3 breakdowns at once to avoid excessive data fragmentation
- With a large number of breakdowns, the number of rows grows exponentially
Working with Breakdowns: Nuances
Empty Values
When using demographic breakdowns, some data may have the value unknown (for example, users without a specified age or gender).
Minimum Data Threshold
Meta Ads may hide rows with a very small amount of data (below a certain threshold) to protect user privacy. In such cases, the sum across breakdowns may not match the overall total.
Performance
Requests with breakdowns take longer to process and place a heavier load on the API. It's recommended to use breakdowns only when segmentation is genuinely necessary.
Recommendations
- Start with aggregated data: analyze overall metrics first, then apply breakdowns for deeper analysis
- Limit the period: for detailed breakdowns, use short periods (7-30 days)
- Use asynchronous reports: for large volumes of data with breakdowns — see Asynchronous Reports