Facebook Page Insights

With the Facebook Page Insights you can access metrics about your Facebook Page. For example you can get the total number of people who liked your Page or the number of people who shared stories about your Page.

Facebook will keep metrics on your Page for 2 years. If your Page is not published, Facebook will only keep 5 days of data.

You can learn about all available metrics and fields in the Insights API Reference.

Prerequisites

Metrics

As of February 5, 2018 all metrics require a page access token of the page of which the insights are being queried. One example is the total number of impressions made by people who saw content associated with your Page. To access such data someone needs to grant you the read_insights permission. Once granted, you can retrieve metrics for all pages owned by this person. If you are not the admin of a Page, you can still read insights about a Page as long as you have a Page Access Token.

To learn more about the Page Access Token please read the manage_pages permission documentation in the sections Login: Permissions and Login: Access Tokens.

Login Review

If your app requests the manage_pages permission, Facebook will review how your app uses it. Learn more about this topic in the Login review documentation.

Page Metrics

To access insight metrics information about a Page simply send a request to the Graph API endpoint /page-id/insights/metric-name. See the Insights Metric documentation for a list of all available metrics. You must include at least one metric in the requested path, or you will receive an error such as:

{
  "error": {
    "message": "Invalid query",
    "type": "OAuthException",
    "code": 3001,
    "error_subcode": 1504028,
    "is_transient": false,
    "error_user_title": "No Metric Specified",
    "error_user_msg": "No metric was specified to be fetched. Please specify one or more metrics to be fetched and try again.",
    "fbtrace_id": "Cs5WotB8WBr"
  }
}

Access a single metric by adding the metric's name to the requested path:

/page-id/insights/page_fan_adds_unique

Or access multiple metric by adding a list of metrics to the requested path:

/page-id/insights/?metric=page_fan_adds_unique,page_fan_adds

If you are admin of the requested Page or are using a Page Access Token granting access to the Page, you will receive a response similar to this:

{
  "data": [
    {
      "name": "page_fan_adds_unique",
      "period": "day",
      "values": [
        {
          "value": 4,
          "end_time": "2016-05-21T07:00:00+0000"
        },
        {
          "value": 3,
          "end_time": "2016-05-22T07:00:00+0000"
        },
        {
          "value": 5,
          "end_time": "2016-05-23T07:00:00+0000"
        }
      ],
      "title": "Daily New Likes",
      "description": "Daily: The number of new people who have liked your Page (Unique Users)",
      "id": "160330740785094/insights/page_fan_adds_unique/day"
    }, 
    ...

When viewing daily metrics with since and until, the first value's end_time will be the date specified by since plus 1 so that it includes the since date data. For example, if you set since to January 1, 2018, the end_time will be January 2, 2018 at 8:00 GMT.

You can learn about all available metrics and fields in the Insights API Reference.

Post Metrics

You can read metrics about single posts as well. To access this information, you need the manage_pages permission. To get metrics about a Post's make a call like /page-id_post-id/insights?metric=post_story_adds_unique,post_story_adds, for example. The shortened response will look like this:

{
  "data": [
    {
      "name": "post_story_adds_unique", 
      "period": "lifetime", 
      "values": [
        {
          "value": 64
        }
      ], 
      "title": "Lifetime Talking About This (Post)", 
      "description": "Lifetime: The number of unique people who created a story by interacting with your Page post. (Unique Users)"
    }, 
    {
      "name": "post_story_adds", 
      "period": "lifetime", 
      "values": [
        {
          "value": 64
        }
      ], 
      "title": "Lifetime Post Stories", 
      "description": "Lifetime: The number of stories generated about your Page post. (Total Count)"
    }, 
    ...

You can learn about all available metrics and fields in the Insights API Reference.

Video Ad Breaks Insights

The Video Ad Breaks Insights allows you to get insights of ads shown during video breaks on your Page. Data is now available for dates after October 15, 2017.

Available Metrics

This API consists of the following metrics:

  • For /insights

    • page_daily_video_ad_break_ad_impressions_by_crosspost_status
    • page_daily_video_ad_break_cpm_by_crosspost_status
    • page_daily_video_ad_break_earnings_by_crosspost_status
    • post_video_ad_break_ad_impressions
    • post_video_ad_break_earnings
    • post_video_ad_break_ad_cpm
  • For /video/insights:

    • total_video_ad_break_ad_cpm
    • total_video_ad_break_ad_impressions
    • total_video_ad_break_earnings

Please refer to the /insights and /video/insights reference docs to view details about these metrics.

Examples

Getting Ad Impressions at the Post Level

You can use Video Ad Breaks Insights to get daily and lifetime ad impressions for a post.

Daily Sample Request

curl -i -X GET \
  "https://graph.facebook.com/8358247707_10156105638467708/insights?metric=post_video_ad_break_ad_impressions&period=day&since=2017-12-10&until=2017-12-14"

Daily Sample Response

{ 
  "data": [
    {
      "name": "total_video_ad_break_ad_impressions",
      "period": "day",
      "values": [
        {
          "value": 2612,
          "end_time": "2017-12-11T08:00:00+0000"
        },
        {
          "value": 1038,
          "end_time": "2017-12-12T08:00:00+0000"
        },
        {
          "value": 818,
          "end_time": "2017-12-13T08:00:00+0000"
        },
        {
          "value": 553,
          "end_time": "2017-12-14T08:00:00+0000"
        }
      ],
      "title": "Daily Video Ad Break Ad Impressions",
      "description": "Number of times an ad was shown during your video ad breaks.",
      "id": "10156105638467708/video_insights/total_video_ad_break_ad_impressions/day"
    }
...

Lifetime Sample Request

curl -i -X GET \
  "https://graph.facebook.com/8358247707_10156105638467708/insights?metric=post_video_ad_break_ad_impressions&period=lifetime"

Lifetime Sample Response

{
  "data": [
    {
      "name": "total_video_ad_break_ad_impressions",
      "period": "lifetime",
      "values": [
        {
          "value": 55468
        }
      ],
      "title": "Lifetime Video Ad Break Ad Impressions",
      "description": "Number of times an ad was shown during your video ad breaks.",
      "id": "10156105638467708/video_insights/total_video_ad_break_ad_impressions/lifetime"
    }
...

Getting Ad Impressions at the Page Level

You can use Video Ad Breaks Insights to get daily ad impressions for a page.

Daily Sample Request

curl -i -X GET \
  "https://graph.facebook.com/8358247707/insights?metric=page_daily_video_ab_break_ad_impressions_by_crosspost_status&period=day&since=2017-12-10&until=2017-12-14"

Daily Sample Response

{
  "data": [
    {
      "name":              "page_daily_video_ad_breaks_ad_impressions_by_crosspost_status",
      "period": "day",
      "values": [
        {
          "value": {
          "crossposted": 27584,
          "owned": 692730
          },
          "end_time": "2017-12-11T08:00:00+0000"
          },
          {
            "value": {
              "owned": 757456,
              "crossposted": 20593
            },
            "end_time": "2017-12-12T08:00:00+0000"
          },
          {
            "value": {
              "owned": 690092,
              "crossposted": 15372
            },
            "end_time": "2017-12-13T08:00:00+0000"
          }
        ],
        "title": "Daily page level videos ad impression",
        "description": "Number of times an ad was shown during ad breaks in your Page's videos, by distribution type (page_owned and crossposted).",
        "id": "8358247707/insights/page_daily_video_ad_break_ad_impressions_by_crosspost_status/day"
      }
...