Marketing API

Insights API Breakdowns

Group the Insights API results into different sets.

The following fields cannot be requested when specifying a breakdown: app_store_clicks, newsfeed_avg_position, newsfeed_clicks, relevance_score and newsfeed_impressions.

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.

Breakdowns

The following breakdowns are available.

BreakdownDescription

action_device

The device on which the conversion event you're tracking occurred. For example, \"Desktop\" if someone converted on a desktop computer.

action_canvas_component_name

Name of a component within a Canvas ad.

action_carousel_card_id

The ID of the specific carousel card that people engaged with when they saw your ad.

action_carousel_card_name

The specific carousel card that people engaged with when they saw your ad. The cards are identified by their headlines.

action_destination

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).

action_reaction

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.

action_target_id

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).

action_type

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.

action_video_sound

The sound status (on/off) when someone plays your video ad.

action_video_type

Video metrics breakdown.

ad_format_asset

The ID of the ad format asset involved in impression, click, or action

age

The age range of the people you've reached.

body_asset

The ID of the body asset involved in impression, click or action.

call_to_action_asset

The ID of the call to action asset involved in impression, click, or action.

country

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.

description_asset

The ID of the description asset involved in impression, click or action.

device_platform

The type of device, mobile or desktop, used by people when they viewed or clicked on an ad, as shown in ads reporting.

dma

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.

frequency_value

The number of times an ad in your Reach and Frequency campaign was served to each person.

gender

Gender of people you've reached. People who don't list their gender are shown as 'not specified'.

hourly_stats_aggregated_by_advertiser_time_zone

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_stats_aggregated_by_audience_time_zone

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.

image_asset

The ID of the image asset involved in impression, click or action.

impression_device

The device where your last ad was served to someone on Facebook. For example \"iPhone\" if someone viewed your ad on an iPhone.

link_url_asset

The ID of the URL asset involved in impression, click or action.

place_page_id

The ID of the place page involved in impression or click.

platform_position

Where your ad was shown within a platform, for example on Facebook desktop News Feed, or Instagram Mobile News Feed.

product_id

The ID and name of the product involved in impression, click, or action.

publisher_platform

Which platform your ad was shown, for example on Facebook, Instagram, or Audience Network.

region

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.

title_asset

The ID of the title asset involved in impression, click or action.

video_asset

The ID of the video asset involved in impression, click or action.

Notes

  • frequency_value is used with reach only. For example, how frequently a unique user saw an ad.
  • By design, image_asset and video_asset breakdowns are not available at the ad account level for assets used in Dynamic Creative.
  • Ad actions video_p25_watched_actions, video_p50_watched_actions, video_p75_watched_actions, video_p95_watched_actions, and video_p100_watched_actions do not support region breakdown.
  • All Dynamic Creative asset breakdowns only support a limited set of metrics:
Dynamic Creative BreakdownsSupported metrics for Dynamic Creative Breakdowns
  • ad_format_asset
  • body_asset
  • call_to_action_asset
  • description_asset
  • image_asset
  • link_url_asset
  • title_asset
  • video_asset
  • impressions
  • clicks
  • spend
  • reach
  • actions
  • action_values

The following call groups the results by age and gender.

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 Breakdowns

Hourly stats are now an available breakdown using the following breakdowns:

  • hourly_stats_aggregated_by_advertiser_time_zone
  • hourly_stats_aggregated_by_audience_time_zone

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 unique_*, reach or frequency. reach and 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"

Action Breakdown

Group results in the actions field. You can use the following breakdowns for action_breakdowns:

The following are the possible breakdowns that can be supplied into the action_breakdowns field.

  • action_device
  • action_canvas_component_name
  • action_carousel_card_id
  • action_carousel_card_name
  • action_destination
  • action_reaction
  • action_target_id
  • action_type
  • action_video_sound
  • action_video_type

If action_breakdowns parameter is not specified, action_type is implicitly added as the action_breakdowns.

Total Count in actions

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 link_click, comment, like, and post_reaction where post_reaction is the count of all Reactions, including likes. total_actions is a sum of top-level actions for an object such as page_engagement, mobile_app_install, and app_custom_event.

Combining Breakdowns

Due to storage constraints, only some permutations of breakdowns are available. Permutations marked with an asterisk (*) can be joined with action_type, action_target_id and action_destination which is the name for action_target_id.

Permutation

action_converted_product_id - Under limited availability for Collaborative Ads.

action_type *

action_type, action_converted_product_id - Under limited availability for Collaborative Ads.

action_target_id *

action_device *

action_device, impression_device *

action_device, publisher_platform *

action_device, publisher_platform, impression_device *

action_device, publisher_platform, platform_position *

action_device, publisher_platform, platform_position, impression_device *

action_reaction

action_type, action_reaction

age *

gender *

age, gender *

country *

region *

publisher_platform *

publisher_platform, impression_device *

publisher_platform, platform_position *

publisher_platform, platform_position, impression_device *

product_id *

hourly_stats_aggregated_by_advertiser_time_zone *

hourly_stats_aggregated_by_audience_time_zone *

action_carousel_card_id / action_carousel_card_name

action_carousel_card_id / action_carousel_card_name

action_carousel_card_id / action_carousel_card_name, impression_device

action_carousel_card_id / action_carousel_card_name, country

action_carousel_card_id / action_carousel_card_name, age

action_carousel_card_id / action_carousel_card_name, gender

action_carousel_card_id / action_carousel_card_name, age, gender

Limitations

  • video_* fields cannot be requested with any hourly stats breakdowns.
  • video_avg_time_watched_actions field cannot be requested with the region breakdown.
  • action_type is implicitly added as the action_breakdowns when action_breakdowns parameter is not specified.