Overview

The Instagram Graph API is built on the Facebook Graph API. It functions in the same way and supports the same features, with the key difference being authentication. If you are unfamiliar with the Graph API, please read our Graph API documentation before proceeding.

Base URL

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

Authentication

All endpoint requests must include a Facebook User access token. However, unlike Facebook users, Instagram users cannot grant your app access tokens directly. Instead, they must connect their Instagram Business Account or Instagram Creator Account to a Facebook Page. Once connected, any Facebook User who is able to perform Tasks on behalf of that Page will be able to grant your app a User access token, which you can then include in API requests.

Use the Facebook Login product to request User access tokens from your app's users. Note that Page tokens are not supported.

Authorization

Endpoint authorization is handled through permissions. The API uses the following permissions:

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

You can use the Facebook Login product to request permissions from your app's users. All of these permissions can be granted by app users while your app 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 users must connect their Instagram Business Account or Instagram Creator Account to a Facebook Page before your app can access the API on their behalf. 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.

Facebook Pages can be connected to a Business or Creator account through the Page's Settings > Instagram tab.

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_content_publish

instagram_manage_comments

instagram_manage_insights

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

Rate Limiting

Starting with v3.3, the Instagram Graph API uses the Business Use Case Rate Limiting logic. When API calls exceed 200 impressions per hour, calls fail.

All responses to calls made to the Instagram Graph API include an x-business-use-case-usage HTTP header. This JSON-formatted string contains your business ID, the current percentage of calls made for that particular Instagram Business User, the total CPU time, the total time, the type of rate limiting being reported, and the estimated time before you can start making calls again if the account has been throttled.

The following example shows an Instagram Business User that has been throttled due to the call count reaching 100%.

x-business-use-case-usage: {
  '{business-id}':  [{
     'call_count':100,        // Percentage of calls made for this Instagram Business User.
     'total_cputime':56,      // Percentage of the total CPU time that has been used.
     'total_time'45,          // Percentage of the total time that has been used.
     'type':'instagram',                      // Type of rate limit logic being applied.
     'estimated_time_to_regain_access'10      // Time in minutes to resume calls.
  }]
}

The values for call_count, total_time, and total_cputime are whole numbers representing the percentage used for each of the metrics. When any of these reach 100, calls will be throttled.

For API v3.2 and older, apps follow the Application level rate limiting logic until July 30, 2019 when all apps will be automatically migrated to the new business use case logic. Upgrade to v3.3 now to apply this new logic.

Please refer to the Graph API's rate limiting documentation for more information.

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.

Limitations