Overview

The Instagram Graph API is a standard REST API that supports basic CRUD operations. It works by checking a User's access token for any Facebook Page roles. If the User has a role on a Page, and that Page is connected to an Instagram Business Account, the User can grant your app permission to access the connected business account's data.

The Basics

The Instagram Graph API is built on the Graph API, so its endpoints consist of nodes, edges on those nodes, and fields.

  • Nodes are your basic objects, such as individual users, photos, and comments.
  • Edges are connections between objects, and are typically used to return all of the objects connected to a single object (node).
  • Fields are properties on an object, and you can often specify which fields you want returned by the API.

Because the API is built in the Graph API, all of its endpoints can be accessed via the graph.facebook.com host. In addition:

  • access requires a valid User access token with specific permissions
  • operations are subject to rate limiting
  • results are returned in JSON format and support pagination (either cursor- or time-based)

Refer to the Graph API documentation for more detailed information about these and additional topics. Note that the Instagram Graph API does not support all of the Graph API's functionality. Unsupported functionality is listed in the Limitations section.

Structure

The Instagram API supports standard CRUD operations. What follows are some sample operations in pseudo-code to help illustrate its structure. If you are already familiar with the Graph API's structure, refer to the reference documentation to learn more about what you can do with each node and any edges it may have.

Most endpoints are simply nodes — object IDs — which can return data (fields) about those objects. For example, here's how to get a specific image object's caption and media_type, using its ID (17895695668004550):

GET graph.facebook.com
  /17895695668004550?fields=caption,media_type

Here is the response. Note that the object's id was automatically included:

{
  "caption": "Desk move day!",
  "media_type": "IMAGE",
  "id": "17895695668004550"
}

Some nodes have an edge which you can use to return collections of objects connected to that node. For example, you could use the /user/media edge to get the IDs of all of the photos on a specific Instagram Business Account (17841405822304914):

GET graph.facebook.com
  /17841405822304914/media

Here's the response:

{
  "data": [
    {
      "id": "17895695668004550"
    },
    {
      "id": "17899305451014820"
    },
    {
      "id": "17896450804038745"
    },
    {
      "id": "17881042411086627"
    },
    {
      "id": "17869102915168123"
    }
  ]
}

Note that edges also allow you to request specific fields. For example, you could modify the request above so that media_type is included in the response (you don't have to ask for id because it is always included):

GET graph.facebook.com
  /17841405822304914/media?fields=media_type

And here's the response:

{
  "data": [
    {
      "media_type": "IMAGE",
      "id": "17895695668004550"
    },
    {
      "media_type": "VIDEO",
      "id": "17899305451014820"
    },
    {
      "media_type": "CAROUSEL_ALBUM",
      "id": "17896450804038745"
    },
    {
      "media_type": "IMAGE",
      "id": "17881042411086627"
    },
    {
      "media_type": "IMAGE",
      "id": "17869102915168123"
    }
  ]
}

Access Tokens

When you use the API to access data on an Instagram Business User, your query must include a Facebook User access token for a User who has a role on the Facebook Page that's connected to the Instagram Business User Account. Page access tokens are not supported.

Each endpoint also requires one or more permissions. You can find this information in each endpoint's reference documentation.

Rate Limiting

The Instagram API uses the same rate limiting as the Graph API (200 calls per user per hour) with one exception: the /media/comments edge limits writes to 60 writes per user per hour. 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.

Roles

Only Users with a role on the Instagram Business Account's connected Facebook Page can grant your app permissions to use the API. Note that the API does not support Business Manager System Users, or Users with Live Contributor roles.

Each role can grant the following permissions:

PermissionAdminEditorModeratorAdvertiserAnalyst

instagram_basic

instagram_content_publish

instagram_manage_comments

instagram_manage_insights

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

Limitations

The Instagram Graph does not support the following Graph API functionality: