Introduction to the Instagram API

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 a 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 the media (photos, videos, and albums) on their 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, you'll learn about the Instagram developer API. 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 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 their 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.

1	GET https://graph.instagram.com/{api-version}/{user-id}
2	?fields={fields}
3	&access_token={access-token}

api-version (optional): The API version, e.g. v14.0 (learn more about versions in the Instagram API documentation). 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.

For example, here's a sample cURL request:

1	curl -X GET \
2	'https://graph.instagram.com/v14.0/10218560180051171?fields=id,username,media_count,account_type&access_token=IGQVJ...'

And here's the sample response:

 {
  "id": "17841405793187218",
  "username": "ubahthebuilder",
  "media_count": 12,
  "account_type": "PERSONAL",
}

The Me Endpoint

The Me endpoint is a shortcut endpoint in that it allows the Instagram user who granted the token to directly access their own 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:

1	GET https://graph.instagram.com/v14.0/me
2	?fields={fields}
3	&access_token={access-token}

It supports the same fields as the User endpoint:

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:

1	GET https://graph.instagram.com/{media-id}
2	?fields={fields}
3	&access_token={access-token}

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.

Note that this endpoint only requires the instagram_graph_user_media permission and returns a single object by its Media ID.

For example, here's a sample cURL request:

1	curl -X GET \
2	'https://graph.instagram.com/13445686989093505?fields=id,media_type,media_url,username,timestamp&access_token=IGQVJ...'

And here's a sample response:

1	{
2	"id": "13445686989093505",
3	"media_type": "IMAGE",
4	"media_url": "https://fb-s-b-a.akamaihd.net/...",
5	"username": "ubahthebuilder"
6	"timestamp": "2022-07-20T18:10:00+0000"
7	}

The Edge Endpoints

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

Here's the syntax for using a path parameter:

// Request an edge on User endpoint
GET https://graph.instagram.com/{user-id}/{edge}
  ?fields={fields}
  &access_token={access-token}

OR:

// Request an edge on Media endpoint
GET https://graph.instagram.com/{media-id}/{edge}
  ?fields={fields}
  &access_token={access-token}

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 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.

1	GET https://graph.instagram.com/{api-version}/{user-id}/media
2	?fields={fields}&access_token={access-token}

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

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

Here's a sample cURL request:

1	curl -X GET \
2	'https://graph.instagram.com/v14.0/13445686989093505/media?fields=id,media_type,media_url,username,timestamp&access_token=IGQVJ...'

And here's the sample response:

 "data": [
    {
        "id": "13445686989093505",
         "media_type": "IMAGE",
        "media_url": "https://fb-s-b-a.akamaihd.net/...",
        "username": "ubahthebuilder"
        "timestamp": "2022-07-20T18:10:00+0000"
    },
    // other media items on the user account
  ],
  "paging": {
    "cursors": {
      "after": "MTAxN...",
      "before": "NDMyN..."
      },
    "next": "https://graph.faceb..."
  }
}

The Media Children Edge

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

Here's the request syntax:

1	GET https://graph.instagram.com/{media-id}/children
2	?access_token={access-token}

The Media ID represents 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.

Here's an example cURL request:

1	curl -X GET \
2	'https://graph.instagram.com/17896450804038745/children?access_token=IGQVJ...'

And here's a response example:

 "data": [
    {
        "id": "13445686989093505",
         "media_type": "IMAGE",
        "media_url": "https://fb-s-b-a.akamaihd.net/...",
        "username": "ubahthebuilder"
        "timestamp": "2022-07-20T18:10:00+0000"
    },
    // other media items on the user account
  ],
  "paging": {
    "cursors": {
      "after": "MTAxN...",
      "before": "NDMyN..."
      },
    "next": "https://graph.faceb..."
  }
}

The Instagram Graph API

With the Instagram Graph 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

The general syntax for this is as follows.

1	GET https://graph.facebook.com/{api-version}/{ig-user-id}
2	?fields={fields}
3	&access_token={access-token}

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.

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

1	curl -X GET \
2	'https://graph.facebook.com/v14.0/17841405822304914?fields=biography%2Cid%2Cusername%2Cwebsite&access_token=EAACwX...'

And here's the sample response:

{
  "biography": "Dino data crunching app",
  "id": "17841405822304914",
  "username": "metricsaurus",
  "website": "https://www.metricsaurus.com/"
}

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.

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:

1	GET https://graph.facebook.com/{api-version}/{ig-user-id}/media
2	?fields={fields}
3	&access_token={access-token}

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, the like 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 Instagram API 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!

Introduction to the Instagram API

Before You Begin

Basic Display API

The User Endpoint

The Me Endpoint

The Media Endpoint

The Edge Endpoints

The User Media Edge

The Media Children Edge

The Instagram Graph API

IG User

Other Endpoints on the Instagram Graph API

What Platforms Does the Instagram API Support?

What's Next?

More Coding For Social Media Tutorials