Facebook Page Insights API

With the Facebook Page Insights API 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

Public Metrics

Some metrics are available publicly, for example, a breakdown by country of a Page's fans known as page_fans_country. You can access these metrics for all Pages using any access token.

Private Metrics

Most of the metrics are private. 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}. 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"
    }, 
    ...

Public Metrics

If you access a Page you are not admin of, you get limited results for metrics like page_fans_country. For example, when you call the Coca Cola Facebook Page at /coca-cola/insights/page_fabs_country, you will get an answer similar to this:

{
  "data": [
    {
      "name": "page_fans_country", 
      "period": "lifetime", 
      "values": [
        {
          "value": {
            "BR": 16765252, 
            "US": 12583676, 
            "MX": 5521869, 
            "AR": 3569248, 
            "FR": 3073083, 
            "IN": 2790080, 
            "TH": 2610519, 
            "GB": 2465121, 
            "IT": 2317926, 
            "ID": 1864923, 
            "CO": 1861586, 
            ...

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.