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-Meta Action Metrics

The following breakdowns will no longer be available for off-Meta action metrics.

Type 1

• region
• dma
• hourly_stats_aggregated_by_audience_time_zone
• hourly_stats_aggregated_by_advertiser_time_zone

Type 2

• action_device
• action_destination
• action_target_id
• product_id
• action_carousel_card_id/action_carousel_card_name
• action_canvas_component_name

Rules related to queries containing above breakdowns:

• Type 1 — The Insights API will not return unsupported offsite metrics (e.g., actions metric with Type 1 breakdowns).
• Type 2 — Offsite web metrics will continue to be returned from the API, however will not contain the breakdown value. The mobile metrics will not be returned anymore when queried with these breakdowns.

Note: The breakdowns listed above will still be supported for on-Meta 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 (this restriction only applies for off-Meta & 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

• Filtering app_id and skan_conversion_id using the filtering field is currently not supported.
• The dma breakdown is not available for the estimated_ad_recall_rate metric or video_thruplay_watched_actions metric.
• The dma breakdown employs a sampling methodology to compute unique metrics like reach. In instances where there are a large number of DMA regions with comparatively low volumes, they might not be represented in the sample or could be scaled up to a power of 2. Therefore, it's advisable to query the corresponding impressions as well for enhanced accuracy.
• 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
• conversion_destination
• matched_persona_id
• matched_persona_name
• signal_source_bucket
• standard_event_content_type
• 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

The total count (sum) of all values returned in group results (actions).

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. The total_actions field represents 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.