Insights API Breakdowns

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.

Limitations

Unavailable fields

The following fields cannot be requested when specifying a breakdown:

• app_store_clicks
• newsfeed_avg_position
• newsfeed_clicks,
• relevance_score
• newsfeed_impressions

Restrictions for off-Facebook action metrics

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:

Type 1

• country
• region
• dma
• hourly_stats_aggregated_by_audience_time_zone
• hourly_stats_aggregated_by_advertiser_time_zone
• age
• gender
• action_device
• device_platform
• platform_position
• publisher_platform
• impression_device
• action_target_id

Type 2

• product_id
• action_carousel_card_id/action_carousel_card_name

Dynamic Creative Breakdowns

• ad_format_asset
• body_asset
• call_to_action_asset
• description_asset
• image_asset
• link_url_asset
• title_asset
• video_asset

Rules related to the above breakdowns:

• Type 1 — These breakdown values are put into "unknown" or "uncategorized" buckets (e.g., for targetId it would be 0).
• Type 2 — The Insights API will not return any rows if the query contains this breakdown along with offsite metrics (e.g., actions metric with Type 2 breakdowns).

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.

Action metrics

Metrics will not be available under the following scenarios:

• When there is an attempted aggregation across multiple attribution settings
• When requested with impacted breakdowns like age, gender, etc. (this restriction only applies for off-Facebook & action types).

Note: Metrics will be available if querying with action_attribution_windows=1d_click,7d_click,1d_view (not including the default window).

Generic Breakdowns

The following breakdowns are available.

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:

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.

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.