Introduction to the Instagram API

by:

Web Development

Following its high-profile acquisition by Facebook in 2012, Instagram adopted two sets of APIs for third-party use. These are the Instagram Graph API and the Instagram Basic Display API.

As a developer building an app that requires information from an user’s authorized Instagram account, your choice of the two APIs depends on the scope of information you want regarding the user.

If you just want basic profile information about the user or a collection of their media (photos, videos and albums) on his or her account, then the Basic Display API will suffice.

However, if you want to get more intricate social media interactions data, metrics and insights about Instagram Businesses and Creator accounts, then you’ll require the Instagram Graph API.

In this tutorial, I’ll give you a broad overview of what you can do with both sets of APIs and how to get started.

Before you begin

To make use of the Instagram API, you’ll need to first create and configure an OAuth app in the App dashboard on your Facebook developer account. This process should result in you getting an API access token which you’ll use in every request to the API.

Please keep in mind that there are two different guides for setting things up:

  • If you want permission to call the Instagram Graph API with your app, follow this guide
  • If you want permission to read basic profile information on an Instagram account (aka Instagram Basic Display API), follow this guide instead.

You should also note that your ability to use certain APIs may depend on the permissions you set for each token in the App dashboard. For this reason, I’ll suggest that you first read this article to see which permission is required for which task.

Using the access token from your app, you can query the API with any HTTP client of your choice.

Basic Display API

With the Instagram Basic Display API, you can tell users of your app to grant you permission to get basic profile information, photos, and videos on their Instagram accounts. The API was created for non-Business and non-Creator Instagram users.

The User Endpoint

The User endpoint allows you to look up basic information about an Instagram user based on his or her User ID. To use this API, your request must include an Instagram User Access Token and the following permissions must be enabled on your Instagram OAuth app:

  • instagram_graph_user_profile
  • instagram_graph_user_media (this is required only if you want the user’s media_count included in the response object)

The request syntax for this endpoint is as follows.

  • api-version (optional): The API version, e.g. v14.0 (learn more about versions here). The value must be a string.
  • user-id (required): The ID of the user you want to get information about. The value must be a string.
  • fields (optional): A comma-delimited list of the fields and edges you want to be returned by the API. If omitted, the default fields will be returned.
  • access_token (required): Your API access token. The value must be a string.

Note that the supported fields for this endpoint are account_type, id, media_count and username. The image below describes what each of these fields returns.

User_fields_imagesUser_fields_imagesUser_fields_images
User fields

For example, here’s a sample cURL request:

And here’s the sample response:

The Me Endpoint

The Me endpoint is a shortcut endpoint in that it allows the Instagram user who granted the token to directly access his or her account. The API does this by first examining the Instagram User Access Token included in the request to determine the ID of the Instagram user who granted the token, then using the ID to query the User endpoint.

Here’s the request syntax:

It supports the same fields as the User endpoint:

User_fields_imageUser_fields_imageUser_fields_image
User fields

Under the hood /me is mapped to /user-id, and the User ID identified by the access token will be used to complete the query.

In summary, this endpoint requires the same scopes as the User endpoint, supports the same fields, and returns a similar object as the response from the API.

The Media Endpoint

With the Media endpoint, you can retrieve information about an Instagram photo, video or album by its Media ID.

Here’s the request syntax:

The supported fields for this endpoint are caption, id, media_type, media_url, username, timestamp, permalink and thumbnail_url. The following image describes what each of these fields returns.

Media fieldsMedia fieldsMedia fields
Media fields

Note that this endpoint only requires the instagram_graph_user_media permission and returns a single media by its Media ID (i.e. it returns an object)

For example, here’s a sample cURL request:

And here’s a sample response:

The Edge Endpoints

Edges allow you to get additional information for an Instagram user or media. You can request an edge as a path parameter or by using the fields query string parameter.

The syntax for using a path parameter:

Both User and Media endpoints support one edge apiece.

The User Media Edge

In addition to the basic profile information, you can also get a collection of media on a user via the User Media edge endpoint. However, there are a few limitations to this that you should keep in mind:

  • The endpoint doesn’t support stories.
  • It also doesn’t support media used in promoted posts.
  • The API returns a maximum of 10K of the most recently created media.

The general syntax for this endpoint is as follows.

In addition to the fields and access_token, this endpoint accepts the following query string parameters:

Query string parametersQuery string parametersQuery string parameters
Query string parameters

With this set of information, you have all it takes to find a media posted in a specific timeframe in your app.

The supported fields for this endpoint are caption, id, media_type, media_url, username, timestamp, permalink and thumbnail_url. The following image describes what each of these fields returns.

Media fieldsMedia fieldsMedia fields
Media fields

Here’s a sample cURL request:

And here’s the sample response:

The Media Children Edge

The Media Children edge endpoint allows you to retrieve a collection of images and video media on an album media.

Here’s the request syntax:

The Media ID represent the album whose children you want to retrieve. This endpoint uses the same OAuth scope as the Media endpoint and uses the same fields. The fields are described in the following image.

Media fieldsMedia fieldsMedia fields
Media fields

Here’s a example cURL request same:

And here’s a response example:

The Instagram Graph API

With the Instagram Basic Display API, you can tell users of your app to grant you permission to access data in their Instagram Business and Creator accounts. This includes permission to get and publish their media, manage and reply to comments on their media, identify media where they have been @-mentioned by other Instagram users, find hashtagged media, and get basic metadata and metrics.

IG User

The IG User endpoint allows you to look up detailed information about an Instagram Business Account or Instagram Creator Account user.

To use the IG User API, you’re required to include an Instagram User Access Token in the request and to have the following OAuth scopes enabled on your Instagram OAuth App:

  • instagram_basic
  • pages_read_engagement
  • pages_show_list
  • ads_management or business_management (If the app user was granted a role on the Page via the Business Manager)
  • catalog_management (if you intend to request the shopping_product_tag_eligibility field for product tagging)
  • instagram_shopping_tag_products (same as the above)

The API also requires the following on the part of the app user you’re intending to retrieve information about (Note: This is only needed if you intend to request the shopping_product_tag_eligibility field):

  • An admin role on the Business manager owning the IG User’s Instagram Shop
  • An approved Instagram Shop with a product catalog containing products

RequirementsRequirementsRequirements
Requirements

The general syntax for this is as follows.

  • api-version (optional): The API version, eg. v14. The value must be a string.
  • user-id (required): The IG User ID of the user you want to get information about. The value must be a string.
  • fields (optional): A comma-separated list of the fields and edges you want to be returned by the API. If omitted, the default fields will be returned.
  • access_token (required): Your API access token. The value must be a string.

The supported fields for this endpoint are biography, id, followers_count, ig_id, follows_count, media_count, name, profile_picture_url, shopping_product_tag_eligibility, username and website. The following image describes what each of these fields returns.

IG User fieldsIG User fieldsIG User fields
IG User fields

For example, here’s a sample cURL request from the docs:

And here’s the sample response:

In addition, the IG User endpoint supports various edges which allow the app to get additional information about the Business or Creator account. These edges are described in the following image.

IG User EdgesIG User EdgesIG User Edges

To get any of these data, you simply need to include the corresponding Edge as an additional path parameter to the IG User endpoint. For example, the following endpoint gets a collection of media on an IG User:

Other Endpoints on the Instagram Graph API

The remaining APIs for working with Business and Creator accounts are:

  • IG Media: This allows you to retrieve information about an Instagram photo, video or album by the Instagram media ID.
  • IG Hashtag: This allows you to retrieve information about a given Instagram hashtag .
  • IG Hashtag Search: This root edge allows you to get Instagram hashtag IDs.
  • IG Container: This allows you to retrieve information about a media container’s publishing status. A media container is used for publishing an Instagram post.
  • IG Comments: This allows you to retrieve comments on a media by the Instagram comment ID. Information returned from the API includes replies to the comment, likes count, and the comment text.

Note that each of these API endpoints may require different OAuth scope permissions on your Instagram app, support a different combination of fields and edges or have certain limitations placed on its usage. As such, make sure to read the complete documentation for clarity.

What Platforms Does the Instagram API Support?

You can access the Instagram API with any platform or programming language using its REST endpoints.

Most programming languages come with a built-in HTTP Client API or a third-party library for making API requests. Examples are axios (Node.js), Net:HTTP (Ruby), requests (Python) and guzzlehttp/guzzle (PHP).

What’s Next?

I hope you’re intrigued to begin using the Instagram API. To get started, simply create a Facebook developer account, refer to the Getting Started guide for instructions on how to retrieve your API token, and start querying the API!

Leave a Reply

Your email address will not be published. Required fields are marked *