Marketing API Version

Insights Breakdowns

Breakdown the insights response into different cohorts.

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

Breakdowns

The following breakdowns are available.

  • age
  • country
  • dma
  • gender
  • frequency_value
  • hourly_stats_aggregated_by_advertiser_time_zone
  • hourly_stats_aggregated_by_audience_time_zone
  • impression_device
  • place_page_id
  • publisher_platform
  • platform_position
  • device_platform
  • product_id
  • region

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

Use 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, whcih are any fields prepended with unique_* or reach.

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 insights in the actions field. You can read more about Action Breakdowns.

Placement Breakdown

Breakdowns can occur in the publisher_platform, platform_position, and impression_device fields. You can read more about placements at Targeting Specs.

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.

video_* fields cannot be requested with any hourly stats breakdowns.

Permutation

action_type *

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