Represents social interaction metrics on your app user's Instagram Media object.
Instagram Insights are now available for Instagram API with Instagram Login. Learn more.
Introducing the views
metric for FEED
, STORY
, and REELS
media product types.
The following metrics have been deprecated for v22.0 and will be deprecated for all versions on April 21, 2025:
plays
clips_replays_count
ig_reels_aggregated_all_plays_count
impressions
Note: API requests with the impressions
metric will continue to return data for media created on or before July 1, 2024 for v21.0 and older. API requests made after April 21, 2025 for media created on or after July 2, 2024 will return an error.
The video_views
metric has been deprecated.
Visit the Instagram Platform Changelog for more information.
This operation is not supported.
GET /<INSTAGRAM_MEDIA_ID>/insights
Get insights data on an Instagram Media object.
0
for individual metrics.Instagram
topic and subscribe to the story_insights
field.10
with the message (#10) Not enough viewers for the media to show insights
.replies
metric now returns a value of 0
.replies
calculations for story media metrics.Instagram API with Instagram Login | Instagram API with Facebook Login | |
---|---|---|
Access Tokens |
| |
Host URL |
|
|
Login Type | Business Login for Instagram | Facebook Login for Business |
Permissions |
|
If the app user was granted a role on the Page connected to your app user's Instagram professional account via the Business Manager, your app will also need:
|
GET "https://<HOST_URL>/<API_VERSION>/<INSTAGRAM_MEDIA_ID>/insights ?metric=<LIST_OF_METRICS> &period=<LIST_OF_TIME_PERIODS> &breakdown=<LIST_OF_BREAKDOWNS> &access_token=<ACCESS_TOKEN>"
Placeholder | Value |
---|---|
The latest version is: v22.0 | The API version your app is using. If not specified in your API calls this will be the latest version at the time you created your Meta app or, if that version is no longer available, the oldest version available. Learn more about versioning. |
| The host URL your app is using to query the endpoint. |
| Required. The Instagram Media ID. |
Key | Placeholder | Value |
---|---|---|
|
| Required. The app user's Facebook or Instagram User access token. |
|
| Designates how to break down results into subsets. |
|
| Required. Comma-separated list of metrics you want returned. |
|
| Comma-separated list of time periods you want returned. Values can be:
|
The following table shows the metrics and the media object types the are available on.
Metric | Media Product Type |
---|---|
Deprecated for v22.0 and for all versions on April 21, 2025. The number of times your reel starts to play again after an initial play of your video. This is defined as replays of 1ms or more in the same reel session. |
|
Number of comments on the media object. |
|
The number of Instagram users following your app user's Instagram professional account. |
|
Deprecated for v22.0 and for all versions on April 21, 2025. The number of times your reel starts to play or replay after an impression is already counted. This is defined as plays of 1ms or more. Replays are counted after the initial play in the same reel session. Note that this count may be greater than the sum of |
|
The average amount of time spent playing the reel. |
|
The total amount of time the reel was played, including any time spent replaying the reel. Metric in development. |
|
Deprecated for v22.0 and for all versions on April 21, 2025. Total number of times your app user's Instagram Media object has been seen. |
|
Number of likes on the media object. |
|
This is the total number of actions taken from your story. These are made up of metrics like exited, forward, back and next story. Available breakdown: |
|
Deprecated for v22.0 and for all versions on April 21, 2025. Number of times the reels starts to play after an impression is already counted. This is defined as video sessions with 1 ms or more of playback and excludes replays. |
|
The number of actions people take when they visit your profile after engaging with your post. Available breakdown: |
|
The number of times your profile was visited. |
|
Number of unique Instagram users that have seen the reel at least once. Reach is different from impressions, which can include multiple views of a reel by the same account. Metric is estimated. |
|
Total number of replies (IG Comments) on the story IG Media object. Value does not include replies made by users in some regions. These regions include: Europe starting December 1, 2020 and Japan starting April 14, 2021. If the Story was created by a user in one of these regions, returns a value of |
|
Number of time your app user's Instagram media was saved by an Instagram user. |
|
Number of shares of the reel. |
|
Number of likes, saves, comments, and shares on the reel, minus the number of unlikes, unsaves, and deleted comments. Metric in development. |
|
Total number of times the video IG Media has been seen. |
|
You can also include the breakdown
parameter for specific metrics to divide data into smaller sets based on the specified breakdown value. Values can be:
breakdown value | Response values |
---|---|
Only compatible with the Break down results by the profile component within the native app that viewers tapped or clicked after viewing the app user's profile. |
|
Only compatible with the Break down results by navigation action taken by the viewer upon viewing the media within the native app. Adding all of these action types will give you the total navigation insights. |
|
NOTE: If you request a metric that doesn't support breakdowns, the API will return an error ("An unknown error has occurred.
"), so be careful if requesting multiple metrics in a single query.
On success your app receives a JSON object containing the results of your query. Results can include the following data, based on your query specifications:
{ "data": [ { "name": "<NAME>", "period": "<PERIOD>", "values": [ { "value": <VALUE> } ], "title": "<TITLE>", "description": "<DESCRIPTION>", "total_value": { "value":<VALUE>, "breakdowns": [ { "dimension_keys": [ "<DIMENSION_KEY_1>", "<DIMENSION_KEY_2>" ... ], "results": [ { "dimension_values": [ "<DIMENSION_VALUE_1>", "<DIMENSION_VALUE_2>" ... ], "value": <VALUE> }, ... ] } ] }, "id": "<ID>" } ] }
Property | Value Type | Description |
---|---|---|
| Array | An array containing an object describing your request results. |
| String | Metric name. |
| String | Period requested. Period is automatically set to |
| Array | An array containing an object describing requested metric values. |
| Integer | For For For |
| String | Metric title. |
| String | Metric description. |
| String | A string describing the query's path parameters. |
| Object | Object describing requested breakdown values (if breakdowns were requested). |
| Array | An array of objects describing the breakdowns requested and their results. |
| Array | Array of strings describing breakdowns requested. |
| Array | An array of objects describing each breakdown set. |
| String | An array of strings describing breakdown set values. Values can be mapped to |
| Object | An object containing URLs used to request the next set of results. See Paginated Results for more information. |
| String | URL to retrieve the previous page of results. See Paginated Results for more information. |
| String | URL to retrieve the next page of results. See Paginated Results for more information. |
The following is a request from an app that uses Facebook Login.
curl -i -X GET \
"https://graph.facebook.com/v22.0
/17932174733377207/insights?metric=profile_activity&breakdown=action_type&access_token=EAAOc..."
{ "data": [ { "name": "profile_activity", "period": "lifetime", "values": [ { "value": 4 } ], "title": "Profile activity", "description": "[IG Insights] This header is the name of a metric that appears on an educational info sheet for a particular post, story, video or promotion. This metric is the sum of all profile actions people take when they engage with this content.", "total_value": { "value": 4, "breakdowns": [ { "dimension_keys": [ "action_type" ], "results": [ { "dimension_values": [ "email" ], "value": 1 }, { "dimension_values": [ "text" ], "value": 1 }, { "dimension_values": [ "direction" ], "value": 1 }, { "dimension_values": [ "bio_link_clicked" ], "value": 1 } ] } ] }, "id": "17932174733377207/insights/profile_activity/lifetime" } ] }
The following is a request from an app that uses Instagram Login.
curl -i -X GET \
"https://graph.instagram.com/v22.0
/17969782069736348/insights?metric=navigation&breakdown=story_navigation_action_type&access_token=EAAOc..."
{ "data": [ { "name": "navigation", "period": "lifetime", "values": [ { "value": 25 } ], "title": "Navigation", "description": "This is the total number of actions taken from your story. These are made up of metrics like exited, forward, back and next story.", "total_value": { "value": 25, "breakdowns": [ { "dimension_keys": [ "story_navigation_action_type" ], "results": [ { "dimension_values": [ "tap_forward" ], "value": 19 }, { "dimension_values": [ "tap_back" ], "value": 4 }, { "dimension_values": [ "tap_exit" ], "value": 1 }, { "dimension_values": [ "swipe_forward" ], "value": 1 } ] } ] }, "id": "17969782069736348/insights/navigation/lifetime" } ] }
This operation is not supported.
This operation is not supported.