Software Architect / Microsoft MVP (AI) and Technical Author

AdTech, Cognitive Services, Facebook API, Instagram Graph API, Prototyping, Social Media, Tooling

Instagram Graph API – Part 2: Fetching data with the Insights API

In Part 1 of this min-series I introduced the Instagram Graph API, what is was, and how you could connect to it.

In Part 2 we look at an API that belongs to the Instagram Graph API – the Insights API.  Specifically, we’ll:

  • introduce the Insights API
  • look at the data you can extract from the Insights API
  • connect to the Insights API and extract valuable image related insights
  • use Postman to validate we can connect to the Insights API out-with the Facebook domain
  • consider some use cases for the Insights API

What exactly is the Insights API?

The Insights API lets you get all insights for individual media objects for a given Instagram account. It features two endpoints

Before you can do this, said account must an Instagram Business Account.  The API features two endpoints:

GET /{ig-media-id}/insights — gets metrics on a media object

GET /{ig-user-id}/insights — gets metrics on an Instagram Business Account or Instagram Creator account.

You can use these endpoints to extract a wide range of metrics for all media that belongs to the Instagram Business accounts that you have access to (for more information about configuring access see Part 1 of this mini-series).

What data can you extract with the Insights API?

So, what data can you extract with the Insights API?

A lot!

The following tables details each metric that is available in the Insights API:

Photo & Video Metrics

Metric Description
engagement Total number of likes and comments on the media object.
impressions Total number of times the media object has been seen.
reach Total number of unique accounts that have seen the media object.
saved Total number of unique accounts that have saved the media object.
video_views (Videos only) Total number of times the video has been seen. Returns 0 for videos in carousel albums.

Carousel Album Metrics

Metric Description
carousel_album_engagement Total number of likes and comments on the
carousel album.
carousel_album_impressions Total number of times the carousel album has been seen.
carousel_album_reach Total number of unique accounts that have seen the carousel album.
carousel_album_saved Total number of unique accounts that have saved the carousel album.

Story Metrics

Metric Description
exits Number of times someone exited the story.
impressions Total number of times the story has been seen.
reach Total number of unique accounts that have seen the story.
replies Total number of replies to the story.
taps_forward Total number of taps to see this story’s next photo or video.

As you can see from the tables above, the Insights API gives you access to valuable metrics such as the total number of likes, comments or even engagement of media that’s being shared by an Instagram account!

Connecting to the Insights API

By now you’ve got overview of what the Insights API is and the data you can expect to extract from it.  Now let’s look at how you can connect to it.  From a process point of view, a good practice before we cut any code is to test the fundamentals.  This will involve:

  1. identifying the Facebook Page ID that is connected to your Instagram Business Account that we want to query (we covered this in Part 1)
  2. identifying a suitable Instagram Media ID
  3. connecting to the Insights API using the Graph API Explorer
  4. supplying the media id to the Insights API in the Graph API Explorer
  5. verifying that we can get Instagram Media meta data
  6. copying the URL we create in the Graph API Explorer and sending this URL using Postman

Using the Graph API Explorer

Please read Part 1 of this tutorial as one of the first things we need to do is identify the Facebook Pages your account as access to.  When you supply this into the Graph Explorer, it will return a list of Pages your account has access to.  You need to take a note of the Page ID and then use this to infer the associated Instagram Business Account.  Again, please read Part 1, it explains all the steps you need to take!

Identifying a suitable Instagram Media ID

By now you’ve identified the Instagram Business Account that’s associated with your Facebook Page.  You can now send requests to the Instagram API!

The first thing we’ll do is identify any media that’s associated with this Instagram Business Account.

To do this you need to send the following query in the Graph Explorer:

https://graph.facebook.com/v3.2/XXX/media?access_token=YYY

Where XXX is the Instagram Business Account ID and YYY is the Access Token you have generated in the Graph API Explorer.

When you send this URL to the Graph API Explorer, it will return the Instagram Media Objects that belong to that user.

You can see this in the screenshot below:

I’m not active on Instagram but have an account for development purposes. If I click on the Media ID (yours will be different), the Graph Explorer will take you to the node:

Extracting Image URL and Number of Comments

Now here is where it gets interesting!

To the left you have the option “Search for a field”.  Enter “media_url” then click Submit. The Graph API will return the URL for the Instagram Media ID Node that we’re currently in:

You can click on this URL; a new tab will open; the image will then be displayed:

For reference, here is the full URL (it’s a test picture I took from an old book I have):

https://scontent.xx.fbcdn.net/v/t51.2885-15/44607845_331662154276372_5860692923554269606_n.jpg?_nc_cat=111&_nc_ht=scontent.xx&oh=14c22e049558c091edcbaaaf94fe4e6b&oe=5D7C0B02

You can add other fields such as “perma_link”, this field will return the link the familiar Instagram Image page:

In this image you can see there is one comment.  You can return the number of comments from the Graph Explorer:

Dive deeper using the Insights API

The values we just extracted sit at the root level for the Media ID in question and you can experiment with other values at your leisure.

You can go deeper with the Insights API endpoint however, for example, you can extract:

  • Engagement (Total number of likes and IG Comments on the IG Media object)
  • Impressions (Total number of times the IG Media object has been seen)
  • Reach (Total number of unique Instagram accounts that have seen the IG Media object)
  • and much more….

You can find out more information about what’s exactly available here.

Identifying the Impressions, Engagement and Reach for an Instagram Media Object

For now, we’ll identify the ImpressionsEngagement and Reach that a Media Object has received.  You can do this by using the following URL in the Graph API Explorer:

MEDIA_ID/insights?metric=impressions,engagement,reach

The Graph API Explorer will then return something like the following.  The notes and values are self-explanatory:

 

{
  "data": [
    {
      "name": "impressions",
      "period": "lifetime",
      "values": [
        {
          "value": 40
        }
      ],
      "title": "Impressions",
      "description": "Total number of times the media object has been seen",
      "id": "17899859863269349/insights/impressions/lifetime"
    },
    {
      "name": "engagement",
      "period": "lifetime",
      "values": [
        {
          "value": 4
        }
      ],
      "title": "Engagement",
      "description": "Total number of likes and comments on the media object",
      "id": "17899859863269349/insights/engagement/lifetime"
    },
    {
      "name": "reach",
      "period": "lifetime",
      "values": [
        {
          "value": 26
        }
      ],
      "title": "Reach",
      "description": "Total number of unique accounts that have seen the media object",
      "id": "17899859863269349/insights/reach/lifetime"
    }
  ]
}

Connecting to the Insights API using Postman

OK, by now you can connect to Insights API and return some data. It’s good to try and connect from a 3rd party application like Postman to make sure you can form the request and required parameters outside of the Facebook domain.  It’ll also help rule out any other connectivity issues, prior to writing any code.

This involves a couple of steps which we’ll run through now.

Copy the Request from the Graph API Explorer

The Graph API Explorer has a few options that let you auto-generate code that constructs a value response along with the required parameters.  At the time of writing it supports the following:

  • Android SDK
  • iOSD SDK
  • JavaScript SDK
  • PHP SDK
  • cURL

To access this, you click on the </> Get Code Button:

You’ll then be presented with a dialogue box, select cURL:

Your only interest in everything between the brackets.  In my case, the full request string consists of the following:

https://graph.facebook.com/v3.2/17899859863269349/insights?metric=impressions%2Cengagement%2Creach&access_token=XXXXXXXXXXX0BAAgSPAn6IpGAh3yPwHHjNsVoYvnTtEM570jZA2CyvUCuG0RTM5dl5fid3ZAZA7DHXN31MTPqPrx8AVvU5xZCZAuWc70EotLlSVofH6HO2RdEpe2ZCHcrowowIgylWjZApRWhxWE5IslK0tlM2BfCcZAjcnNDLfpiMQ2durqpgx6ZBNXOT1yria8B6iA1RMMxrJBqxbiYXY25ZB

Take a copy of this request string, we’ll use this in Postman.

Execute in Postman

Now we have the fully formed request from the Graph API Explorer we can use this in Postman.  Create a new GET Request and past the request string into the address bar:

Click Send, your request will be sent to the Instagram Insights API which will return JSON similar to the following!

It’s a good time to recap. So far, we’ve:

  • Connected to the Facebook Graph API
  • Located the Facebook Pages and Instagram Business Accounts that our User has access to
  • Identified the Instagram Business Account ID
  • Constructed requests using the Facebook Graph API Explorer
  • Extracted a list of Instagram Business Media Objects
  • Extracted root level meta data for an Instagram Media Object
  • Extracted Insight data for an Instagram Media Object
  • Constructed and Submitted a request using Postman to verify that we can invoke the Facebook and Instagram Graph API outside the Facebook domain

There are quite a few steps here and we’ve covered a lot.  I recommend having a look through the Facebook and Instagram Developer API reference guides.  You’ll find other Nodes, Edges and Fields that let you surface other valuable datapoints!

Sample use cases for the Instagram API

Having programmatic access to Facebook and Instagram data opens the possibility for developers to build innovative solutions for many use cases.

Some examples that immediately spring to mind are:

Monitoring your Marketing Campaign

Maybe you’re promoting products and services on Instagram and whilst you can track the volume of sales through your CRM, you’re unsure how many eyeballs are on your Instagram marketing efforts or how many people are commenting on your content. As we’ve just seen, you can use the Insights API to track important KPIs such as impressions, engagement or the total number of comments per Instagram Media object.

Search by Hashtag

With the Hashtag Search API, you can list all media objects per with a given hashtag or even list the most popular images tagged with a given hashtag.  You can use this insight to help to gauge what sort of content is resonating with your audience.

Audience Insights

The Insights API has another endpoint which lets you extract data associated your followers. For example, you can extract a list of all cities, countries or even the age and gender distribution of your followers.  Use this data to help you better understand your audience and help drive your content creation strategy.

Another useful metric you can extract is the follower count for a given day.  You can write code that will aggregate this data over a given time period, thereby giving you further insights as to when the best time to share content is.

This is something I had to build as part of in interface for researchers involved in the National Geographic Photo Ark Project.  They were interested in helping National Geographic raise awareness of environmental and animal welfare issues.

Part of this involved surfacing content that was raising the number of followers daily, thereby providing researchers and the National Geographic Photo Ark Team with insight as to the types of images photographers should be taking more of and sharing on Instagram.

Identify Trends by Location

Interested in identifying trends by location? Filter users by their location, then run the Hashtag Search API to surface the most popular hashtags.  Run a second query with those hashtags and extract all media with said tags.  You then have a collection of images that are trending in that location!

Custom Dashboards

Do you need to aggregate data from all your social media channels into one easy to read screen? You can use the Facebook, Twitter and Instagram APIs to do just that! With some custom development you can use theses APIs to blend together datasets that give you a holistic view of all your social media data.

Summary

In this blog post we’ve introduced the Insights API. We’ve seen how you can connect to it using the Graph API Explorer and explored some of the data you can extract from the API. We’ve looked at how you can construct and send a request using Postman to the Insights API for testing purposes.

From a business perspective, we’ve identified several use cases for the Insights API, I’m sure you’ve probably got your own ideas brewing!

Are you considering building software that integrates with the Instagram Graph API?
Do you have any further questions?

Drop me a note!

JOIN MY EXCLUSIVE EMAIL LIST
Get the latest content and code from the blog posts!
I respect your privacy. No spam. Ever.

25 Comments

  1. Judi Kartu

    This page definitely has alⅼ tһe inhfo I neseded conceгning this subject
    aand ⅾidn’t know who to ask.

  2. George Edwards

    Great post! Quick question if you don’t mind advising –

    Is it possible to query media insights for ANOTHER user’s postings? An example would be if I wanted to obtain insights from Apple’s posts.

  3. Marty

    Hi Jamie,

    This was a great write-up. It really lays out the requirements needed for build and development. I have a few outstanding metrics I’m trying to ingest from the Instagram API – one of them being “post shares”. I don’t see this throughout Instagram’s documentation. Any idea on that metric?

    • Comment by post author

      jamie_maguire

      Hey Marty,

      I’m glad you like the write up and got some value from it. I had a look and can’t see that exact metric. Here is the main URL that has all ID media metrics: https://developers.facebook.com/docs/instagram-api/reference/media/insights

      In the coming weeks I’m going to be publishing V2 of the Instagram eBook. It’ll feature and end to end web application in .NET Core that uses the code that was created in this series + Azure Cognitive Services to surface further insights.

      You can then view these insights in the Web Application. I’m planning to retail this out of the box solution (price TBD).

  4. Leo

    Quick question : Is it possible to retrieve bulk information for multiple media id’s at once.

  5. handoyo

    Hi Jamie,

    Thanks for the tutorial. I wonder if it’s possible for use to get other business daily followers count?

    • Comment by post author

      jamie_maguire

      You’re welcome. I doubt this is possible as you need an acccess token for that business (unless you can be assigned as an admin and generate the token on their behalf). I’d also check what’s available under the public permissions.

  6. Marty

    Hi Jamie,

    Would you know of any explanation why Carousel_Album_Impressions would decrease and than increase back up? Since this is a lifetime metric, I would think this should only increase over time. Unfortunately, the UI platform for Instagram doesn’t show trend over time to where I could reference the data for historical dates.

    Thanks for any input.

    Marty

    • Marty

      Hi Jamie,

      I think I figured out our issue. We thought we could get historical data from the lifetime tables, but I don’t think that’s possible. I.e. On 10/21/20, you are getting the lifetime data for that day, you can’t go back and get 8/30/20 ‘s data on 10/21. Let me know if you feel that is accurate.

      Marty

      • Comment by post author

        jamie_maguire

        Hi Marty, from memory I believe you can only get the last 24 hours data. I’d need to check tho. I know that’s certianly the case for Stories.

        I’ve written a new eBook which has an end to end web application that uses this API. You can find it here: https://gum.co/Nmnrr

  7. Kristie Focht

    Does anyone know the common link between FB and IG when querying data? Example, I want to know how my boosted posts are doing vs organic posts. Boost info is in FB, and engagement is in IG – how do I tie the two together in my query?

  8. Faizan Manzoor

    Is it possible to get total followers of instagram account using graph api insight?

    I tried but it return only last month data.

  9. Vinay

    I used graph API to call Stories Media ID but How can I know which story it is? Using Story URL

  10. Hi Jamie,

    Great post – helps a lot!

    I was wondering if you know, whether the new IG Graph API, allows for data older than 24 months? The reason I’m asking is that the demographic on my platform which shows age/gender distribution in terms of followers doesn’t reflect the total number of followers. For instance, an influencer has 5,000 followers, but the age/gender distribution only accounts for approx. half of that. As if the age/gender breakdown only accounts for followers within the last 24 months?

    I was hoping to find a solution that allows an overall/historical distribution.

    Thanks.

    Brgds,
    Oliver

    • Comment by post author

      jamie_maguire

      Hi Oliver,

      Glad you liked it!

      I don’t believe the IG Graph supports that. You would have to store that data and report over it yourself.

      I’ve done several IG graph extractions in the past for clients.

      I’ve bundled everything into an eBook. It also contains code for a full blown IG Analytics web application + source code. You might be interested in it.

      You can find it here: https://jamie-maguire1.gumroad.com/l/Nmnrr

      • Oliver

        Hi Jamie,

        Thanks for your response. I’ve checked out your link, and it looks very interesting.

        I have another question you might be able to help with. I’ve seen that other platforms are able to identify top interests among followers i.e. 35% are interested in fashion and clothing, is that something the IG Graph API delivers? Or how do they find such information? I guess it’s something associated with scraping for hashtags, but as far as I’m concerned, Facebook/Instagram are trying to prohibit such techniques.

  11. Syed

    Thanks, I need to write an app in C# that allows me to forward Reels, IGTV Post, Messages and other user message to forward or put on my Story or friend circle

    can you please help me in this regard?

  12. Daniel

    Thanks Jamie,

    Is there a way to get access to a business instagram account insights that doesn’t belong to me with an app in developer mode? how can I request a permission to do that?

  13. flyff

    fantastic points altogether, you just won a new reader.
    What would you recommend about your post that you made some days ago?
    Any positive?

  14. (#100) For field ‘insights’: The parameter metric is required

    My query is :

    media-id/media?fields=id,caption,like_count,comments_count,permalink,insights&limit=1000

    i can get impressions by media-id/insights?metric=impressions&period=days_28

    but that will cost me n +1 requests for n posts. I need to get all the details like caption like_count and insights in one request. any help here on how to pass metric here?

    • /media?fields=id,caption,like_count,comments_count,permalink,insights.metric(impressions)&limit=1000

      above was working and getting me impressions but only for the posts after my account conversion to business account

      i have 68 posts before account conversion and 1 post after conversion

      I get only 1 post which was made after conversion if I pass insights parameter
      , but get all posts if skip insights
      looks like insights only works for posts posted after account conversion

Leave a Reply