Facebook Instagram Graph API

Written by Chris Bovan

Facebook Instagram Graph API allows you to programmatically access Instagram Business Accounts so you can more easily manage media objects, view comments and metadata, and get insights and metrics with custom built apps. If you are building apps for Instagram Non-Business Accounts, Instagram Platform API should be used instead.

Facebook Instagram Graph API

Concrete Social API vs. Facebook Instagram API

Concrete Social API is using offical Facebook Instagram API. It does so by offering its users data-less API access. This means that unlike offical API that offers data analytics features - our API is only for publishing. It may seem like a limitation but the fact that official API has all data as part of it - getting approved for access to that API has become nearly impossible.

Instagram Graph API

Instagram Graph API consists the 4 main areas:

  • Mentions API Facilitates interactions between businesses and people. Allow them to see media they have been photo tagged or @mentioned in and reply back.

  • Business Discovery API Discover other businesses. Learn how other businesses manage their Instagram presence by viewing their organic posts.

  • Insights API Help businesses access and analyze valuable metrics about their Instagram business profile. Enable them to understand and optimize the performance of their organic content on Instagram.

  • Comment Moderation API Drive interactions at scale. Enable businesses to more efficiently interact with their audience through comments under their media on Instagram.

  • Content Publishing API The Content Publishing API is a subset of Instagram Graph API endpoints that allow you to publish media objects. Publishing media objects with this API is a two step process — you first create a media object container, then publish the container on your Business Account.

  • Webhooks Webhooks for Instagram allows you to receive real-time notifications whenever Instagram Users comment on any of your media objects, @mention your business on other Instagram Users’ media objects, or when your Stories expire.

  • Hashtag Search API The Hashtag Search API allows you to find public photos and videos that have been tagged with specific hashtags.

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 (all endpoints support cursor-based pagination, but the /{user-id}/insights edge is the only endpoint that supports time-based pagination)

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"
}

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.

Limitations

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

  • ordering results