Overview

The Instagram Basic Display API is an HTTP-based API that apps can use to get an Instagram user’s profile, images, videos, and albums.

Components

Base URLs

• api.instagram.com — for getting Instagram User Access Tokens
• graph.instagram.com — for getting Instagram user profiles and media

Versions

The API supports the same versioning protocol and release cycle as the Facebook Graph API. New versions are released approximately every 3 months and each version will be available for roughly 2 years before deprecation.

To query a specific API version, include the version number in the query path after the base URL. For example:

https://graph.instagram.com/v11.0/10218560180051171/media

If you omit the version number from your request, the request will resolve to the version specified in the App Dashboard > Settings > Advanced > Upgrade API Version section.

Authorization Window

The Authorization Window allows your app to get Authorization Codes and permissions from app users. Authorization Codes can be exchanged for Instagram User Access Tokens, which must be included when querying an app user's profile or their media.

To implement the Authorization Window, refer to our Getting Access Tokens guide.

Authorization Codes

Authorization Codes can be exchanged for short-lived Instagram User Access Tokens. To get an Authorization Code, implement the Authorization Window into your app. After an app user authenticates their identity through the window and grants your app any permissions it needs, we will redirect the user to your app and include an Authorization Code. You can then use the API to exchange the code for the app user's short-lived Instagram User Access Token.

Authorization Codes are short-lived and are only valid for 1 hour.

Instagram User Access Tokens

API authentication is handled by Instagram User Access Tokens that conform to the OAuth 2.0 protocol. Access tokens are app-scoped (unique to the app and user pair) and can be short-lived or long-lived. API requests that query Instagram users or their media must include an Instagram User Access Token.

Short-Lived Access Tokens

Short-lived access tokens are valid for 1 hour, but can be exchanged for long-lived tokens. To get a short-lived access token, implement the Authorization Window into your app. After the app user authenticates their identity through the window, we will redirect the user back to your app and include an Authorization Code, which you can then exchange for a short-lived access token.

Long-Lived Access Tokens

Short-lived tokens that have not expired can be exchanged for long-lived access tokens which are valid for 60 days. Long-lived tokens can be refreshed before they expire by querying the GET /refresh_access_token endpoint.

Permissions

Data access authorization is controlled by your app users through the use of the permissions listed below. Users must grant your app these permissions through the Authorization Window before your app can access their data.

• instagram_graph_user_profile — allows your app to read the User node, which represents the Instagram user, and the node’s edges.
• instagram_graph_user_media — allows your app to read the Media node, which represents an image, video, or album, and the node’s edges.

Instagram testers can grant your app these permissions at any time. In order for app users without a role on your app to be able to grant your app these permissions, each permission must first be approved for Advanced Access through the App Review process, and your app must be in Live mode.

Permission grants made by app users with public accounts are valid for 90 days. Refreshing an app user's long-lived access token will extend the permission grant for another 90 days if the app user who granted the token has a public account. If the app user's account is private, however, the permission grant cannot be extended and the app user must grant the expired permission to your app again.

Instagram Testers

In order to test your app with an Instagram User, you must first send an invitation to the Instagram User's account and accept the invitation. Invitations can be sent from the Instagram Testers section in the App Dashboard > Roles > Roles tab.

Invitations can be accepted by the Instagram User in the (Profile Icon) > Edit Profile > Apps and Websites > Tester Invites section of the Instagram website or mobile app after signing into their account.

Resources

Data in the API consists of Instagram users and their media (images, videos, and albums). All data is protected by permissions; in order for your app to access a user’s data, the user must grant your app permission to do so through the Authorization Window.

Users

Instagram users and their profiles are represented by User nodes. Note that Instagram Legacy API User IDs are incompatible with the Instagram Basic Display API.

Media

Photos, videos, and albums are represented by Media nodes and are created on individual Users.

Rate Limits

All endpoint requests are subject to Graph API’s Platform Rate Limiting.

You can see your app's current call count consumption in the App Dashboard > Instagram > Basic Display Rate Limiting tab after adding the Instagram product to your app.

App Types

Apps designated as Business apps are not supported. If your app is a Business app use the Instagram Graph API instead, or create a new, non-Business app.

App Review

Instagram testers can grant your app Instagram permissions at any time. In order for app users without a role on your app to be able to grant your app Instagram permissions, each permission must first be approved for Advanced Access through the App Review process, and your app must be in Live mode.

When you have completed app development and are ready to switch your app to Live Mode, review our App Review, Sample Submissions, and Common Rejection Reasons documents to learn about the App Review process. Once you are familiar with the process, you can request approval for Instagram Basic Display API permissions through the App Dashboard > Products > Instagram > Basic Display tab.

If you are creating an app solely for the purpose of generating access tokens with the User Token Generator, you do not need to submit your app for App Review. The User Token Generator does not require any permissions and can be used while your app is in Development Mode.

Business Verification

While your app is in Development Mode it will only be able to access data in Instagram Tester accounts. Before you can switch your app to Live Mode and access data in non-tester accounts, you must first complete Business Verification.

How It Works

To use the API, first get the Authorization Window and present it to an app user. The app user authenticates their identity through the window and authorizes your app to access their data by granting your app specific permissions. Once authenticated, the window redirects back to your app and includes an Authorization Code. Capture the code and exchange it for a short-lived Instagram User Access Token. Once you have a short-lived token, you can use it to query User and Media endpoints for any data the user has permitted your app to access, or exchange it for a long-lived token.

Tools

User Token Generator

The Instagram User Token Generator is a tool you can use to quickly generate long-lived Instagram User Access Tokens for any of your public Instagram accounts. This is useful if you’re testing your app and don’t want to bother with implementing the Authorization Window, or if you’re using copy and pasteable code supplied by a third-party service (for example, to display your own Instagram data on your own website).

The tool works by triggering the Authorization Window, which you can sign into with a public Instagram account that you have designated as a tester account. After signing in, the tool will generate a long-lived access token that you can copy and paste. Note that tokens can only be generated for public Instagram accounts.

You can access the token generator in the App Dashboard > Products > Instagram > Basic Display tab.

If you are creating an app solely for the purpose of generating access tokens with the User Token Generator, you do not need to submit your app for App Review. The User Token Generator does not require any permissions and can be used while your app is in Development Mode.

Next Steps

Follow our Get Started guide to learn how to set up an app and perform a basic API request.