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

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"
    }, 
    ...

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.