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:
- identifying the Facebook Page ID that is connected to your Instagram Business Account that we want to query (we covered this in Part 1)
- identifying a suitable Instagram Media ID
- connecting to the Insights API using the Graph API Explorer
- supplying the media id to the Insights API in the Graph API Explorer
- verifying that we can get Instagram Media meta data
- 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 Impressions, Engagement 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!
Judi Kartu
This page definitely has alⅼ tһe inhfo I neseded conceгning this subject
aand ⅾidn’t know who to ask.
jamie_maguire
Glad you got some value from it Judi.
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.
jamie_maguire
Glad you like it George!
I had to do something similar in the past for National Geographic / Photo Ark and you can’t get this data directly.
You need the accounts permission to do that.
Nitya
Great post, It is very useful. I have a similar question
I am working on fetching details like follower count, likes and comments, media , insights of any Instagram business accounts user. How can I get the engagement of other users?Can you please tell me the exact permission name? My API endpoint as of now looks like this
https://graph.facebook.com/version/Instagram_business_account_id?fields=business_discovery.username(username){followers_count,media_count,media{comments_count,likes_count}}
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?
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).
Leo
Quick question : Is it possible to retrieve bulk information for multiple media id’s at once.
handoyo
Hi Jamie,
Thanks for the tutorial. I wonder if it’s possible for use to get other business daily followers count?
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.
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
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
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?
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.
Vinay
I used graph API to call Stories Media ID but How can I know which story it is? Using Story URL
Oliver Hansen
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
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.
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?
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?
jamie_maguire
You’re welcome Daniel.
No, you can’t do that. You need to build an app with OAuth Authentication then get go through the application verification process. I’m currently doing this with my SaaS – http://www.socialopinion.co.uk
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?
Ameer Hamza
(#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?
Ameer Hamza
/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