You can group the Insights API results into different sets using breakdowns.
The Insights API can return several metrics that are estimated, in development, or both. Insights breakdown values are estimated. For more information, see Insights API, Estimated and Deprecated Metrics.
The following fields cannot be requested when specifying a breakdown:
The following breakdowns will no longer be available for off-Facebook action metrics with the exception of metrics for app campaigns exclusively targeting Android or iOS 14.4 and below:
Dynamic Creative Breakdowns
Rules related to the above breakdowns:
targetIdit would be
Note: The breakdowns listed above will still be supported for on-Facebook metrics such as impressions, link clicks, etc. The changes will also not impact historical data prior to April 27, 2021; breakdowns for historical data will continue to be available.
Metrics will not be available under the following scenarios:
Note: Metrics will be available if querying with
action_attribution_windows=1d_click,7d_click,1d_view (not including the default window).
The following breakdowns are available.
The device on which the conversion event you're tracking occurred. For example, \"Desktop\" if someone converted on a desktop computer.
Name of a component within a Canvas ad.
The ID of the specific carousel card that people engaged with when they saw your ad.
The specific carousel card that people engaged with when they saw your ad. The cards are identified by their headlines.
The destination where people go after clicking on your ad. This could be your Facebook Page, an external URL for your conversion pixel or an app configured with the software development kit (SDK).
The number of reactions on your ads or boosted posts. The reactions button on an ad allows people to share different reactions on its content: Like, Love, Haha, Wow, Sad or Angry.
The ID of destination where people go after clicking on your ad. This could be your Facebook Page, an external URL for your conversion pixel or an app configured with the software development kit (SDK).
The kind of actions taken on your ad, page, app or event after your ad was served to someone, even if they didn't click on it. Action types include page likes, app installs, conversions, event responses, and more.
The sound status (on/off) when someone plays your video ad.
Video metrics breakdown.
The ID of the ad format asset involved in impression, click, or action
The age range of the people you've reached.
The ID of the application associated with the Ad Account or Campaign requested. The application information, including it’s ID, is viewable in the App Dashboard.
Note: This breakdown is only supported by the
The ID of the body asset involved in impression, click or action.
The ID of the call to action asset involved in impression, click, or action.
The countries where the people you've reached are located. This is based on information such as a person's hometown, their current city and the geographical location where they tend to be when they visit Facebook.
The ID of the description asset involved in impression, click or action.
The type of device, mobile or desktop, used by people when they viewed or clicked on an ad, as shown in ads reporting.
DMA (Designated Market Area) regions are the 210 geographic areas in the United States in which local television viewing is measured by The Nielsen Company.
The number of times an ad in your Reach and Frequency campaign was served to each person.
Gender of people you've reached. People who don't list their gender are shown as 'not specified'.
Hourly breakdown aggregated by the time ads were delivered in the advertiser's time zone. For example, if your ads are scheduled to run from 9 AM to 11 AM, but they reach audiences in multiple time zones, they may deliver from 9 AM to 1 PM in the advertiser's time zone. Stats will be aggregated into four groups 9 AM - 10 AM, 10 AM - 11 AM, 11 AM - 12 PM, and 12 PM - 1 PM.
Hourly breakdown aggregated by the time ads were delivered in the audiences' time zone. For example, if your ads are scheduled to run from 9 AM to 11 AM but they reach audiences in multiple time zones, they may deliver from 9 AM to 1 PM in the advertiser's time zone. Stats will be aggregated into two groups 9 AM - 10 AM and 10 AM - 11 AM.
The ID of the image asset involved in impression, click or action.
The device where your last ad was served to someone on Facebook. For example \"iPhone\" if someone viewed your ad on an iPhone.
The ID of the URL asset involved in impression, click or action.
The ID of the place page involved in impression or click.
Note: Account level insights and
Where your ad was shown within a platform, for example on Facebook desktop Feed, or Instagram Mobile Feed.
The ID and name of the product involved in impression, click, or action.
Which platform your ad was shown, for example on Facebook, Instagram, or Audience Network.
The regions where the people you've reached are located. This is based on information such as a person's hometown, their current city and the geographical location where they tend to be when they visit Facebook.
The assigned Conversion ID (also referred to as Priority ID) of the event and/or event bundle configured in the application’s SKAdNetwork configuration schema. The app events configuration can be viewed and adjusted in Facebook Events Manager. You can learn more about configuring your app events for Apple's SKAdNetwork here.
Note: This breakdown is only supported by the
The ID of the title asset involved in impression, click or action.
The ID of the video asset involved in impression, click or action.
filteringfield is currently not supported.
dmabreakdown is not available for the
frequency_valueis used with
reachonly. For example, how frequently a unique user saw an ad.
video_assetbreakdowns are not available at the ad account level for assets used in Dynamic Creative.
video_p100_watched_actionsdo not support
|Dynamic Creative Breakdowns||Supported metrics for Dynamic Creative Breakdowns|
The following call groups the results by
curl -G \ -d "breakdowns=age,gender" \ -d "fields=impressions" \ -d "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/<API_VERSION>/<AD_CAMPAIGN_ID>/insights"
Hourly stats are now an available breakdown using the following breakdowns:
See Combining Breakdowns for limits on number of breakdowns you may request with the hourly breakdown. Hourly breakdowns do not support unique fields, which are any fields prepended with
frequency fields will return 0 when hourly breakdowns are in use.
curl -G \ -d "fields=impressions" \ -d "breakdowns=hourly_stats_aggregated_by_audience_time_zone" \ -d "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/<API_VERSION>/<AD_CAMPAIGN_ID>/insights"
Group results in the
actions field. You can use the following breakdowns for
The following are the possible breakdowns that can be supplied into the
action_breakdowns parameter is not specified,
action_type is implicitly added as the
Sum up all values returned in
actions. Note this result may not equal
total_actions since fields returned in
actions are hierarchical includes detailed actions not counted.
total_actions - 33 page_engagement - 10 post_engagement - 10 link_click - 2 comment - 3 post_reaction - 3 like - 2 mobile_app_install - 12 app_custom_event - 11 app_custom_event.fb_mobile_activate_app - 6 app_custom_event.other - 5
In this example, post_engagement is a sum of
post_reaction is the count of all Reactions, including likes.
total_actions is a sum of top-level actions for an object such as
Due to storage constraints, only some permutations of breakdowns are available. Permutations marked with an asterisk (*) can be joined with
action_destination which is the name for
video_*fields cannot be requested with any hourly stats breakdowns.
video_avg_time_watched_actionsfield cannot be requested with the region breakdown.
action_typeis implicitly added as the
action_breakdownsparameter is not specified.