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:
instagram_basicinstagram_content_publishinstagram_manage_commentsinstagram_manage_insightsinstagram_shopping_tag_productspages_show_listpages_read_engagement- Instagram Public Content Access
Refer to our endpoint reference to determine which permission and features your app will need to request from app users.
Instagram Messaging
If you plan to implement Instagram Messaging from Messenger Platform, you will need to include the instagram_manage_messages permission.
Learn more about Instagram Messaging.
Collaborators
The Instagram Collab feature allows Instagram app users to co-author content (i.e. publish media) with other accounts (collaborators).
With a few exceptions, data on or about co-authored media can only be accessed through the API by the user who published the media; collaborators are unable to access this data via the API. The only exceptions are when searching for top performing media or recently published media that has been tagged with a specific hashtag. See Hashtag Search.
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 or change the Facebook Page connected to your Instagram professional 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:
| Permission | MANAGE | CREATE_CONTENT | MODERATE | ADVERTISE | ANALYZE |
|---|---|---|---|---|---|
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:
| Role | Grantable Permissions |
|---|---|
Editor | instagram_basic |
Moderator | instagram_basic |
Advertiser | instagram_basic |
Analyst | instagram_basic |
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 Access | Grantable Permissions |
|---|---|
Ads | instagram_basic |
Content | instagram_basic |
Insights | instagram_basic |
Messages & Community Activity | instagram_basic |
To determine if a Page is using the new experience, request its has_transitioned_to_new_page_experience field. This value return true if the Page uses the new experience.
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.
Instagram Messaging
Several Instagram Graph API endpoints are used in conjunction with the Messenger Platform endpoints to allow your app users to interact with direct messages sent to their Instagram Professional accounts. Refer to the Messenger Platform's Instagram Messaging documentation to learn how to access messages in Instagram Business accounts.