Marketing API Version

Insights Breakdowns

Group the Insights 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.

Generic Breakdowns
Hourly Breakdowns
Action Breakdowns
Placement Breakdowns
Combining Generic Breakdowns and Action Breakdowns

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

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_canvas_component_name
action_carousel_card_id
action_carousel_card_name
action_destination
action_device
action_link_click_destination
action_reaction
action_target_id
action_type
action_video_sound
action_video_type

This groups results from the call by action_link_click_destination.

curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
-d 'fields=actions' \
-d 'action_breakdowns=action_link_click_destination' \
'https://graph.facebook.com/<API_VERSION>/<AD_OBJECT_ID>/insights'

The response looks like this:

{
  "data": [
    {
      "actions": [
        {
          "action_type": "comment",
          "value": "5"
        },
        {
          "action_type": "like",
          "value": "2"
        },
        {
          "action_type": "post",
          "value": "10"
        },
        {
          "action_type": "post_reaction",
          "value": "100"
        },
        {
          "action_link_click_destination": "click_to_app_deeplink",
          "action_type": "link_click",
          "value": "100"
        },
                {
          "action_link_click_destination": "click_to_app_store",
          "action_type": "link_click",
          "value": "200"
        },
        {
          "action_link_click_destination": "click_to_call",
          "action_type": "link_click",
          "value": "300"
        },
        {
          "action_link_click_destination": "click_to_canvas",
          "action_type": "link_click",
          "value": "400"
        },
        {
          "action_link_click_destination": "click_to_form",
          "action_type": "link_click",
          "value": "500"
        },
        {
          "action_link_click_destination": "click_to_get_directions",
          "action_type": "link_click",
          "value": "600"
        },
        {
          "action_link_click_destination": "click_to_marketplace",
          "action_type": "link_click",
          "value": "700"
        },
        {
          "action_link_click_destination": "click_to_message",
          "action_type": "link_click",
          "value": "800"
        },
        {
          "action_link_click_destination": "click_to_website",
          "action_type": "link_click",
          "value": "900"
        },
        {
          "action_link_click_destination": "unknown",
          "action_type": "link_click",
          "value": "1000"
        },
      ],
      "date_start": "2017-05-06",
      "date_stop": "2017-06-04"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

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.

Placement Breakdown

Breakdowns can occur in the publisher_platform, platform_position, and impression_device fields. You can read more about placements with Targeting Specs. There are breakdowns by platform_position for Facebook, Instagram, and Audience Network.

For example to see stats for each Audience Network positions, use the publisher_platform platform_position breakdown:

GET act_<AD_ACCOUNT_ID>/insights?
breakdowns=["publisher_platform","platform_position"]

The response looks like this:

{
  "data": [
    {
    ....
    {
      "date_start": "2017-06-05",
      "date_stop": "2017-07-04",
      "impressions": "1812604",
      "spend": "8487.62",
      "account_id": "<ACCOUNT_ID>",
      "publisher_platform": "audience_network",
      "platform_position": "an_classic"
    },
    {
      "date_start": "2017-06-05",
      "date_stop": "2017-07-04",
      "impressions": "294787",
      "spend": "4627.19",
      "account_id": "<ACCOUNT_ID>",
      "publisher_platform": "audience_network",
      "platform_position": "rewarded_video"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "NQZDZD"
    }
  }
}

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_link_click_destination`
`action_reaction`
`action_type, action_reaction`
`action_type, action_link_click_destination`
`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`