Overview
Meta offers a number of Insights APIs to allow you to view insights for specific posts, Stories, videos, reels, and Live videos on Ad Accounts, Instagram Accounts, Messenger and Instagram Messaging Accounts, and Facebook Pages. You can view performance and engagement and overall trends across your followers and your content’s performance with your audience.
How It Works
Insights APIs allow you to call an endpoint to get specific metric or metrics about a node that you are interested in.
What You Need
The following are components you may need to implement and concepts you will need to know to make successful calls to any of the Insights APIs.
Access Levels
There are two access levels for permissions and features you can request for your app, Standard Access and Advanced Access. Due to the limited scope for Standard Access, some products and features may not work properly until your app has been granted Advanced Access in App Review. This may limit any test apps you use. Learn more.
App Review
You must complete App Review if your app will need Advanced Access for a permission or feature. Learn more.
Access Tokens
An access token is an opaque string that identifies an app, Facebook Page, or person and can be used by an app to make secure API calls to Meta. An access token provides secure access to specific endpoints that allows your app to get insights data. Learn more.
System User Access Tokens
A system user represents a server or software making API calls to assets owned or managed by a Business Manager. You may wish to use a system user access token to authenticate your calls to insights endpoints or to create a long-lived access token.
Business Verification
You must complete Business Verification if your app will need Advanced Access for a permission or feature. Learn more.
Facebook Login
A secure, fast, and convenient way for users to log into your app, and for your app to ask for permissions to access data. Facebook Login enables two scenarios, authentication and asking for permissions to access people's data. You can use Facebook Login simply for authentication or for both authentication and data access. Learn more.
Features and Permissions
Features are a form of app-granted Graph API authorization. Before your app can access certain endpoints, your app must be granted permission to a specific feature. You can apply to use a feature during app review.
Permissions are a form of granular, user-granted Graph API authorization. Before your app can use an endpoint to access an app user's data, the app user must grant your app all permissions required by that endpoint. The easiest way to get permissions from app users is to implement Facebook Login.
Meta Registration
You will need to register as a developer and register your app with Meta to make calls to any Meta endpoints. Learn more.
Page Tasks
The person requesting access to the insights for content about or on a Facebook Page using your app must be able to perform the ANALYZE task on the Facebook Page. Page admins can perform all tasks on a Page.
Learn more.
Special API Parameters
To query a specific time period, you can use the since and until parameters when querying an endpoint. The until parameter is not inclusive which means the end time is midnight of the previous day. Let’s work with an example:
To get metrics for the entire month of July 2022, the parameters must be set to:
since=1656658800 // July 1, 2022
until=1659423600 // August 2, 2022
Data from July 1, 2022 at 12:00:00am to July 31, 2022 at 11:59:59pm will be returned in this query.
Learn more.
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.
Next Steps
Get Started – Learn how to make a basic request to an Insights endpoint.