Overview

The Instagram Graph API is a collection of Facebook Graph API endpoints that allow apps to access data in Instagram Professional accounts (both Business and Creator accounts). If you are unfamiliar with the Facebook Graph API, please read our Graph API documentation before proceeding.

Base URL

All endpoints can be accessed via the graph.facebook.com host.

App Users

Instagram Professional accounts are accessed indirectly through Facebook accounts so your app users must have a Facebook account and use it when signing into your app. In addition, the Facebook account must be able to perform admin-equivalent Tasks on a Facebook Page that has been connected to the Instagram account they are trying to access.

These requirements apply to all app users, even those who have a Role on your app or a Role on a Business that has claimed your app.

Authentication

App user authentication is handled through access tokens. Instagram Professional accounts are accessed indirectly through Facebook accounts, so all API requests must include your app users's Facebook User access token. You can get tokens from app users by implementing Facebook Login. Note that Facebook Login does not support Instagram credentials so app users must sign in using a Facebook account.

Authorization

Endpoint authorization is handled through permissions and features. Before your app can use an endpoint to access an app user's Instagram data, you must first request all permissions required by those endpoints from the app user. The app user must then grant those permissions to your app. Once granted, you can query the endpoints to access the user's data.

Note that a permission only allows access to data created by the user who granted the permission. There are a few endpoints that allow apps to access data not created by the app user, but the accessible data is limited and public.

You can request permissions from app users by implementing Facebook Login. App users who have a role on your app can grant any requested permissions. App users who do not have a role on your app can only grant permissions and features that have been approved through the App Review process.

The API uses the following permissions and features:

Refer to our endpoint reference to determine which permission and features your app will need to request from app users.

Pages

Instagram Professional accounts must be connected to a Facebook Page before their data can be accessed through the API. Once connected, any Facebook User who is able to perform Tasks on that Page can grant your app an access token, which can then be used in API requests.

Our Add a Facebook Page to your Instagram Business Account help article explains how to connect to a Facebook Page to an Instagram Professional account.

Tasks

In order for an app user to grant your app permissions, the app user must be able to perform tasks on the Facebook Page connected to the Instagram account they are attempting to access. App users may grant your app permissions based on tasks they are able to perform as follows:

PermissionMANAGECREATE_CONTENTMODERATEADVERTISEANALYZE

instagram_basic

instagram_content_publish

instagram_manage_comments

instagram_manage_insights

You can determine which tasks an app user is able to perform on a Page by querying the GET /me/accounts endpoint with the app user's User access token. The endpoint will return a list of Pages that the app user is able to perform tasks on, and indicate which tasks the user can perform on each of them.

Refer to the reference documentation to see which permissions each endpoint requires. The API does not support Business Manager System Users, or app users who have the Live Contributor role.

Referring to tasks

If you need to inform your app users about tasks (and which ones are required to use your app properly), here's how tasks are referred to in our various UIs.

Classic Pages

Classic Pages refer to tasks as roles. App users with an Admin role on a Page can grant your app any permission. App users with other roles can grant permissions as follows:

RoleGrantable Permissions

Editor

instagram_basic
instagram_content_publish

Moderator

instagram_basic
instagram_manage_comments
instagram_manage_insights

Advertiser

instagram_basic
instagram_manage_insights

Analyst

instagram_basic
instagram_manage_insights

New Experience Pages

New Experience Pages refer to tasks as either Facebook Access or Task Access. App users with Facebook Access on a Page can grant your app any permission. App users with Task Access can grant permissions as follows:

Task AccessGrantable Permissions

Ads

instagram_basic

Content

instagram_basic
instagram_content_publish

Insights

instagram_basic
instagram_manage_insights

Messages & Community Activity

instagram_basic
instagram_manage_comments

There's no easy way to determine if a Page is using the classic or new experience, so when informing an app user about task access, refer to both. For example, "To perform this action you must have Facebook Access or Content Task Access, or an Admin or Editor role on this page."

App Review

Your app must complete App Review before it can be used by app users who do not have a Role on your app or a Role on a Business that has claimed your app. If your app will only be used by app users who have a Role on your app or Business, you do not need to complete App Review.

Your App Review submission does not need to include any Facebook test user credentials if you have implemented Facebook Login and your app is publicly available. However, if our reviewers need to sign into a non-Facebook account in order to trigger your implementation of Facebook Login, you must include the non-Facebook account credentials in your submission.

Private Apps

If our reviewers are unable to test your app because it is behind a private intranet, has no user interface, or has not implemented Facebook Login, you may only request approval for these Permissions:

Business Verification

You must complete Business Verification if your app will be used by app users who do not have a Role on the app itself, or a Role in a Business that has claimed the app.

Rate Limiting

All endpoints are subject to Instagram Business Use Case rate limiting except for Business Discovery and Hashtag Search endpoints, which are subject to Platform Rate limiting.

Webhooks

You can use Webhooks to have notifications sent to you whenever someone comments on your app users' media objects or when any of their stories expire. Refer to our Webhooks documentation to learn how to use Webhooks, then set up a webhook for the Instagram topic and subscribe to its comments and story_insights fields.