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 User access token. However, unlike Facebook Users, Instagram Business Users cannot grant your app access tokens directly. Instead, they must connect their Instagram Business User 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 Business Users must connect their account to a Facebook Page before your app can access their data. Once connected, any Facebook User who is able to perform Tasks on that Page can grant your app an access token, which can be used to query the connected Instagram Business User's data.

Facebook Pages can be connected to an Instagram Business User through the Page's Settings > Instagram tab.

Tasks

Only Facebook Users who can perform Tasks on the Facebook Page connected to the Instagram Business User's 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.

A User who can perform a task can grant the following permissions:

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.

App Review

All Instagram Graph API permissions except for pages_show_list require approval through the App Review process before your app users can grant them to your app while it is in Live Mode. You can request approval for permissions in the App Review > Permissions and Features tab within the App Dashboard.

In addition to App Review, you must complete Business Verification and agree to our Supplemental Terms before you can switch your app to Live mode.

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 any of your media objects or when any of your 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