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.

Access Tokens

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.

Permissions

Endpoint authorization is handled through Permissions. The API uses the following Permissions and Features:

Refer to the reference documentation to see which Permissions each endpoint requires.

You must implement Facebook Login in order to request Permissions from your app users. All of these Permissions can be granted by any app user who has a Role on your app or a Role on a Business that has claimed your app while it is in Development Mode. However, with the exception of pages_show_list, your app must be approved for these Permissions through the App Review process before app users can grant them to your app while it is in Live Mode.

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

Only Facebook Users who can perform Tasks on the Facebook Page connected to the Instagram Business or Creator Account can grant your app User access tokens and permissions to use the API. Note that the API does not support Business Manager System Users, or Users with Live Contributor defined roles.

Permissions can be granted by Facebook Users according to the tasks they are able to perform:

PermissionMANAGECREATE_CONTENTMODERATEADVERTISEANALYZE

instagram_basic

instagram_manage_comments

instagram_manage_insights

Refer to the reference documentation to see which permissions each endpoint requires.

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.