Facebook Pages API

Get Page Insights

This guide explains how to get metrics for your Facebook Pages. Get the total number of people who liked your Page or the number of people who shared stories about your Page.

Limitations

  • Metric data of public Pages is stored by Facebook for 2 years.
  • Metric data of unpublished Pages is stored for only 5 days.
  • When viewing daily metrics with since and until, the first end_time value 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.

Before You Start

Get a Single Metric

Send a GET request to the /{page-id}/insights/{metric-name} endpoint:

curl -i -X GET "https://graph.facebook.com/{page-id}/insights/page_impressions_unique
  ?access_token={page-access-token}"

On success your app receives the following response:

{
  "data": [
    {
      "name": "page_impressions_unique",
      "period": "day",
      "values": [
        {
          "value": 66226,
          "end_time": "2020-03-10T07:00:00+0000"
        },
        {
          "value": 78037,
          "end_time": "2020-03-11T07:00:00+0000"
        }
      ],
      "title": "Daily Total Reach",
      "description": "Daily: The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more. (Unique Users)",
      "id": "{page-id}/insights/page_impressions_unique/day"
    },
    {
      "name": "page_impressions_unique",
      "period": "week",
      "values": [
        {
          "value": 202229,
          "end_time": "2020-03-10T07:00:00+0000"
        },
        {
          "value": 206982,
          "end_time": "2020-03-11T07:00:00+0000"
        }
      ],
      "title": "Weekly Total Reach",
      "description": "Weekly: The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more. (Unique Users)",
      "id": "{page-id}/insights/page_impressions_unique/week"
    },
    {
      "name": "page_impressions_unique",
      "period": "days_28",
      "values": [
        {
          "value": 427380,
          "end_time": "2020-03-10T07:00:00+0000"
        },
        {
          "value": 432909,
          "end_time": "2020-03-11T07:00:00+0000"
        }
      ],
      "title": "28 Days Total Reach",
      "description": "28 Days: The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more. (Unique Users)",
      "id": "{page-id}/insights/page_impressions_unique/days_28"
    }
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{page-id}/insights?access_token={page-access-token}&pretty=0&metric=page_impressions_unique&since=1583568000&until=1583737200",
    "next": "https://graph.facebook.com/{page-id}/insights?access_token={page-access-token}&pretty=0&metric=page_impressions_unique&since=1583910000&until=1584082800"
  }
}

Get Multiple Metrics

Send a GET request to the /{page-id}/insights endpoint with the metric field:

curl -i -X GET "https://graph.facebook.com/{page-id}/insights
  ?metric=page_impressions_unique,page_engaged_users
  &access_token={page-access-token}"

On success, your app receives the following response:

{
  "data": [
    {
      "name": "page_impressions_unique",
      "period": "day",
      "values": [
        {
          "value": 66226,
          "end_time": "2020-03-10T07:00:00+0000"
        },
        {
          "value": 78037,
          "end_time": "2020-03-11T07:00:00+0000"
        }
      ],
      "title": "Daily Total Reach",
      "description": "Daily: The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more. (Unique Users)",
      "id": "{page-id}/insights/page_impressions_unique/day"
    },
    {
      "name": "page_engaged_users",
      "period": "day",
      "values": [
        {
          "value": 1458,
          "end_time": "2020-03-10T07:00:00+0000"
        },
        {
          "value": 1673,
          "end_time": "2020-03-11T07:00:00+0000"
        }
      ],
      "title": "Daily Page Engaged Users",
      "description": "Daily: The number of people who engaged with your Page. Engagement includes any click or story created. (Unique Users)",
      "id": "{page-id}/insights/page_engaged_users/day"
    },
    {
      "name": "page_impressions_unique",
      "period": "week",
      "values": [
        {
          "value": 202229,
          "end_time": "2020-03-10T07:00:00+0000"
        },
        {
          "value": 206982,
          "end_time": "2020-03-11T07:00:00+0000"
        }
      ],
      "title": "Weekly Total Reach",
      "description": "Weekly: The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more. (Unique Users)",
      "id": "{page-id}/insights/page_impressions_unique/week"
    },
    {
      "name": "page_engaged_users",
      "period": "week",
      "values": [
        {
          "value": 10527,
          "end_time": "2020-03-10T07:00:00+0000"
        },
        {
          "value": 10593,
          "end_time": "2020-03-11T07:00:00+0000"
        }
      ],
      "title": "Weekly Page Engaged Users",
      "description": "Weekly: The number of people who engaged with your Page. Engagement includes any click or story created. (Unique Users)",
      "id": "{page-id}/insights/page_engaged_users/week"
    },
    {
      "name": "page_impressions_unique",
      "period": "days_28",
      "values": [
        {
          "value": 427380,
          "end_time": "2020-03-10T07:00:00+0000"
        },
        {
          "value": 432909,
          "end_time": "2020-03-11T07:00:00+0000"
        }
      ],
      "title": "28 Days Total Reach",
      "description": "28 Days: The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more. (Unique Users)",
      "id": "{page-id}/insights/page_impressions_unique/days_28"
    },
    {
      "name": "page_engaged_users",
      "period": "days_28",
      "values": [
        {
          "value": 35472,
          "end_time": "2020-03-10T07:00:00+0000"
        },
        {
          "value": 35625,
          "end_time": "2020-03-11T07:00:00+0000"
        }
      ],
      "title": "28 Days Page Engaged Users",
      "description": "28 Days: The number of people who engaged with your Page. Engagement includes any click or story created. (Unique Users)",
      "id": "{page-id}/insights/page_engaged_users/days_28"
    }
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{page-id}/insights?access_token={page-access-token}&pretty=0&metric=page_impressions_unique%2Cpage_engaged_users&since=1583568000&until=1583737200",
    "next": "https://graph.facebook.com/{page-id}/insights?access_token={page-access-token}&pretty=0&metric=page_impressions_unique%2Cpage_engaged_users&since=1583910000&until=1584082800"
  }
}

Get Metrics of a Page Post

Send a GET request to the /{page-post-id}/insights endpoint with the metric fields:

curl -i -X GET "https://graph.facebook.com{page-post-id}/insights
  ?metric=post_reactions_like_total,post_reactions_love_total,post_reactions_wow_total
  &access_token={page-access-token}"

On success, your app receives the following response:

{
  "data": [
    {
      "name": "post_reactions_like_total",
      "period": "lifetime",
      "values": [
        {
          "value": 226
        }
      ],
      "title": "Lifetime Total Like Reactions of a post.",
      "description": "Lifetime: Total like reactions of a post.",
      "id": "{page-post-id}/insights/post_reactions_like_total/lifetime"
    },
    {
      "name": "post_reactions_love_total",
      "period": "lifetime",
      "values": [
        {
          "value": 17
        }
      ],
      "title": "Lifetime Total Love Reactions of a post.",
      "description": "Lifetime: Total love reactions of a post.",
      "id": "{page-post-id}/insights/post_reactions_love_total/lifetime"
    },
    {
      "name": "post_reactions_wow_total",
      "period": "lifetime",
      "values": [
        {
          "value": 1
        }
      ],
      "title": "Lifetime Total wow Reactions of a post.",
      "description": "Lifetime: Total wow Reactions of a post.",
      "id": "{page-post-id}/insights/post_reactions_wow_total/lifetime"
    }
  ],
  "paging": {
    "previous": "https://graph.facebook.com/{page-post-id}/insights?access_token={page-access-token}b&pretty=0&metric=post_reactions_like_total%2Cpost_reactions_love_total%2Cpost_reactions_wow_total&since=1583568000&until=1583737200",
    "next": "https://graph.facebook.com/{page-post-id}/insights?access_token={page-access-token}&pretty=0&metric=post_reactions_like_total%2Cpost_reactions_love_total%2Cpost_reactions_wow_total&since=1583910000&until=1584082800"
  }
}

Get Video Ad Breaks Impressions

Additional Requirements

Send a GET request to the /{page-id} endpoint to get daily Video Ad Breaks impressions for a Page:

curl -i -X GET \
  "https://graph.facebook.com/{page-id}/insights
    ?metric=page_daily_video_ad_break_ad_impressions_by_crosspost_status
    &period=day
    &since=2017-12-10
    &until=2017-12-14"

On success, your app receives the following 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": "{page-id}/insights/page_daily_video_ad_break_ad_impressions_by_crosspost_status/day"
      }
...

Get Daily Video Ad Break Impressions of a Page Post

Send a GET request to the /{page-post-id}/insights endpoint with the metric field:

curl -i -X GET "https://graph.facebook.com/{page-post-id}/insights
  ?metric=post_video_ad_break_ad_impressions
  &period=day
  &since=2017-12-10
  &until=2017-12-14
  &access_token={page-access-token}"

On success, your app will receive the following 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": "{video-id}/video_insights/total_video_ad_break_ad_impressions/day"
    }
...

Get Lifetime Video Ad Break Impressions of a Page Post

curl -i -X GET "https://graph.facebook.com/{page-post-id}/insights
  ?metric=post_video_ad_break_ad_impressions
  &period=lifetime
  &access_token={page-access-token}"

On success, your app will receive the following 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": "{video-id}/video_insights/total_video_ad_break_ad_impressions/lifetime"
    }
...

Error Codes

Error CodeError MessageDescription

190

"The 'manage_pages' permission must be granted before impersonating a user's page."

You need the manage_pages permission in order to access this endpoint.

None

An empty dataset is returned.

You need the read_insights permission in order to access this endpoint.

100

"(#100) The value must be a valid insights metric"

The may be a spelling or syntax issue.

190

"The 'manage_pages' permission must be granted before impersonating a user's page."

You need the manage_pages permission in order to access this endpoint.

3001 with "error_subcode": 1504028

"No metric was specified to be fetched. Please specify one or more metrics to be fetched and try again."

When using the metric parameter, at least one metric must be included in the query.

See Also