Get Started with the Page Insights API

The Page Insights API provides you with valuable metrics about your Facebook pages. On this guide you will find all you need to know about how to get started with the Page Insights API: from generating the tokens to doing your first request.

What you’ll need

1. Basic understanding of HTTP, APIs and JavaScript Object Notation (JSON);

2. A Meta Developer account (you can create one);

3. An app for which you have a role, such as an admin, developer, or tester role. (you can create one). A business type app is recommended since the necessary permissions are already pre approved;

4. A Facebook page in which you can perform the ANALYZE task;

Generate a token

You will need a page access token with the necessary permissions. You can generate a page access token using our Graph API Explorer.

The permissions you need for this API are:

• read_insights
• pages_show_list
• pages_read_engagement

Choose the metrics you want to query

There are dozens of different metrics available under the Page Insights API. You can access the full list of metrics here.

For this tutorial the chosen metrics are page_engaged_users and page_impressions.

This way our parameter will be: metrics=page_engaged_users,page_impressions.

Define the interval

You can set the since and until parameters to define an interval for data retrieval. It’s important to notice that the until parameter is non-inclusive and considers the end_time as midnight of the previous day. Let’s work with an example:

Let’s say we want to get metrics for the whole month of July 2022.

The parameters must be set as:

since=2022-07-01

until=2022-08-02

This way the last value returned will have the end_time of 2022-08-01 at midnight, which translates to values from 2022-07-31 at midnight to 2022-08-01 at midnight.

Choose the aggregation periods

The aggregation period is a sum of the metric values in the past X days. If you select the week value for the period, you’ll get the sum of the last 7 days from the date you are querying.

You can choose more than one aggregation period at the same time. For the purpose of this tutorial, we will choose period=day,week.

Note: Some aggregation periods are not compatible with certain metrics, make sure to check the documentation.

Call the API

You can call the API using lots of different tools, such as our Graph API Explorer, Postman or CURL.

Final request:

https://graph.facebook.com/{page-id}/insights?access_token={page-access-token}&metric=page_engaged_users,page_impressions&since=2022-07-01&until=2022-08-02&period=day,week

Understand the response

The API response is a JSON containing an array of data. The array elements correspond to the metrics queried and their aggregation period. For each day queried you can check the corresponding end_date and metric value.

There were 34824 page impressions on October 2nd, 2022. If we check the same day but with the weekly aggregation period, we get a value of 2384604.

Sample response:

{
   "data": [
       {
           "name": "page_impressions_unique",
           "period": "day",
           "values": [
               {
                   "value": 34824,
                   "end_time": "2022-10-03T07:00:00+0000"
               },
               {
                   "value": 38637,
                   "end_time": "2022-10-04T07: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"
       },
   ]
}