Represents social interaction metrics on an IG Media object.
This operation is not supported.
GET /{ig-media-id}/insights
Get insights data on an IG Media object.
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.0
for individual metrics.Type | Description |
---|---|
If the app user was granted a role on the Page via the Business Manager, you will also need one of: |
GET https://graph.facebook.com/{api-version}/{ig-media-id}/insights ?metric={metric} &access_token={access-token}
Placeholder | Value |
---|---|
| API version. |
| Required. IG Media ID. |
Parameter | Value |
---|---|
Type: string | Required. App user's User access token. |
Type: Comma-separated list | Required. Comma-separated list of Metrics you want returned. |
Some of these metrics are deprecated for v18.0. They will be deprecated for all versions beginning Dec 11, 2023. Please use the alternative metrics listed.
total_interactions
, which is listed as an alternative for some of the deprecated metrics, is currently only available using version 18.0 and does not work with older versions. When querying older versions before Dec 11, 2023, please use the engagement
metric.
See the Changelog for more information.
Metric | Description |
---|---|
| Total number of likes and IG Comments on the album IG Media object. |
| Total number of times the album IG Media object has been seen. |
| Total number of unique Instagram accounts that have seen the album IG Media object. |
| Total number of unique Instagram accounts that have saved the album IG Media object. |
| Total number of unique Instagram accounts that have viewed video IG Media within the album. |
Metrics on media within an album are not supported. Get metrics on the album instead.
Metric | Description |
---|---|
| Sum of |
| Total number of times the IG Media object has been seen. |
| Total number of unique Instagram accounts that have seen the IG Media object. |
| Total number of unique Instagram accounts that have saved the IG Media object. |
| Total number of times the video IG Media has been seen. For album IG Media, the number of times all videos within the album have been seen. |
Metric | Description |
---|---|
| The number of times your reel starts to play again after an initial play of your reel. This is defined as replays of 1ms or more in the same reel session. |
| Number of comments on the reel. Metric in development. |
| 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. |
| The average amount of time spent playing the reel. Metric in development. |
| The total amount of time the reel was played, including any time spent replaying the reel. Metric in development. |
| Number of likes on the reel. Metric in development. |
| 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. Metric in development. |
| Number of unique accounts 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 and in development. |
| Number of saves of the reel. Metric in development. |
| Number of shares of the reel. Metric in development. |
| Number of likes, saves, comments, and shares on the reel, minus the number of unlikes, unsaves, and deleted comments. Metric in development. |
Metric | Description |
---|---|
| Total number of times someone exited the story IG Media object. |
| Total number of times the story IG Media object has been seen. |
| Total number of unique Instagram accounts that have seen the story IG Media object. |
| 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 |
| Total number of taps to see this story IG Media object's next photo or video. |
| Total number of taps to see this story IG Media object's previous photo or video. |
curl -X GET \
'https://graph.facebook.com/v19.0
/17895695668004550/insights?metric=impressions,reach&access_token=IGQVJ...'
{ "data": [ { "name": "impressions", "period": "lifetime", "values": [ { "value": 264 } ], "title": "Impressions", "description": "Total number of times the media object has been seen", "id": "17855590849148465/insights/impressions/lifetime" }, { "name": "reach", "period": "lifetime", "values": [ { "value": 103 } ], "title": "Reach", "description": "Total number of unique accounts that have seen the media object", "id": "17855590849148465/insights/reach/lifetime" } ] }
The metrics listed below are new and will gradually be made available to all developers. These metrics will eventually replace the legacy metrics listed above. If you see this message you are able to use the new metrics described below.
GET https://graph.facebook.com/{api-version}/{ig-media-id}/insights ?metric={metric} &breakdown={breakdown} &access_token={access-token}
Key | Placeholder | Value |
---|---|---|
|
| Required. The app user's User access token. |
|
| Designates how to break down result set into subsets. See Breakdown. |
|
| Required. Comma-separated list of Metrics you want returned. |
You can also specify one or more breakdowns, and the results will be broken down into smaller sets based on the specified breakdown. Values can be:
action_type
— Only compatible with the profile_activity metric. Break down results by profile UI component that viewers tapped or clicked after viewing the app user's profile. Response values can be:
BIO_LINK_CLICKED
CALL
DIRECTION
EMAIL
OTHER
TEXT
story_navigation_action_type
— Break down results by navigation action taken by the viewer upon viewing the media.
TAP_BACK
TAP_EXIT
TAP_FORWARD
SWIPE_FORWARD
Refer to the Metrics table to determine which metrics support breakdowns and which breakdowns they support. 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.
The following metrics are available on image and video IG Media published as a Post. Album carousels and IGTV are not supported.
Metric | Breakdown | Description |
---|---|---|
| n/a | The number of comments on your post. |
| n/a | The number of accounts that started following you. |
| n/a | The number of likes on your post. |
|
| The number of actions people take when they visit your profile after engaging with your post. |
| n/a | The number of times your profile was visited. |
| n/a | The number of shares of your post. |
| n/a | The number of likes, saves, comments and shares on your post minus the number of unlikes, unsaves and deleted comments. |
The following metrics are available on IG Media published as a Story.
Metric | Breakdown | Description |
---|---|---|
| n/a | This is how many accounts started following you. |
|
| This is the total number of actions taken from your story. These are made up of metrics like exited, forward, back and next story. |
|
| The number of actions people take when they visit your profile after engaging with your story. |
| n/a | The number of times your profile was visited. |
| n/a | The number of shares of your story. |
| n/a | The number of replies and shares for your story. |
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. |
curl -i -X GET \
"https://graph.facebook.com/v19.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" } ] }
curl -i -X GET \
"https://graph.facebook.com/v19.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.