Marketing API Version



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.


The following breakdowns are available.

  • age
  • country
  • gender
  • frequency_value
  • hourly_stats_aggregated_by_advertiser_time_zone
  • hourly_stats_aggregated_by_audience_time_zone
  • impression_device
  • place_page_id
  • placement
  • 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>" \

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

Note that in the Combining Breakdowns section that there are a limited number of breakdowns you may request along side the hourly breakdown.

Additionally, these hourly breakdowns don't support any unique fields (e.g. 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>" \

Action Breakdown

Action Breakdowns are breakdowns that occur in the actions field. You can read more about action breakdowns here.

Placement Breakdown

Breakdowns can occur in the publisher_platform, platform_position, and impression_device fields. You can read more about placements with 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 (the name for action_target_id).

video_* fields cannot be requested when using any hourly stats breakdowns.


action_type *

action_target_id *

action_device *

action_device, placement *

action_device, placement, 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_type, action_reaction

age *

gender *

age, gender *

country *

region *

placement *

placement, impression_device *

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, placement

action_carousel_card_id / action_carousel_card_name, placement, 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