Get Started

This tutorial shows you how to create an API call to read a metric from your Facebook Page.

Before You Start

This tutorial assumes you have read and implemented the needed components, such as a Meta Developer Account and App ID, a Facebook Page, and more, listed in the Insights APIs Overview for calling an Insights API from Meta.

You need the following:

A Facebook Page that you own or administer, or on which you can perform the ANALYZE task
A Meta App ID – You do not need a live app to get a Meta App ID but you must be listed as having a role on the Meta app such as an admin, developer or tester
The read_insights, page_show_list, and pages_read_engagement permissions if you are using your app

Step 1: Get a Page and Access Token

You can get a Page access tokens using one of the following methods:

Facebook Login in your app
The Graph API Explorer

Use the Graph API Explorer

Open the Graph API Explorer
Edit the Query String Field to me/accounts?fields=name,id,access_token,tasks
Add the pages_show_list, pages_read_engagement, and read_insights permissions
Click Generate Access Token
Click Submit

You should see a list of Facebook Pages you have a role on. Find a Page for which you have the ANALYZE task and copy the Page ID and the access token string.

Step 2. Get a Single Metric

You can read data for a single metric. The format for a single metric endpoint is:

/{page-id}/insights/{metric-name}

Get Unique Page Impressions

To get unique Page impressions, send a GET request to the /{page-id}/insights/page_impressions_unique endpoint.

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

A successful API call will return a JSON object with the impression counts for all time periods available for this metric, daily, weekly, and 28 days.

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

You can read data for multiple metrics in one API call. The format for multiple metrics endpoint is:

/{page-id}/insights?metric={metric-name},{metric-name}

where metrics are in a comma separated list.

Get Page Impressions and Engagements

In this example we are getting data for the number of people who had any content from your Page or about your Page enter their screen and the number of people who engaged with your Page by sending a GET request to the /{page-id}/insights?metric=page_impressions_unique,page_engaged_users endpoint.

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

A successful API call will return a JSON object with the impression and engaged users counts for all time periods available for these metrics, daily, weekly, and 28 days.

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