IG Media Insights

IGTV media is now supported in v10.0+. This applies to all endpoints except those used for content publishing and webhooks. To support this change, new media_product_type and video_title fields have been added to the IG Media node. IGTV media must have been shared to Instagram at the time of publish (Post a Preview or Share Preview to Feed enabled) in order to be accessible via the API.

Represents social interaction metrics on an IG Media object.

Due to privacy rules, messaging-related Story IG Media interactions performed by users in some regions will no longer be included in some metric calculations. These regions include: Europe starting December 1, 2020 and Japan starting April 14, 2021.

For Stories created by users in affected regions, the replies metric will now return a value of 0.
For Stories created by users outside affected regions, the replies metric will return the number of replies, but replies made by users in affected regions will not be included in the calculation.

Creating

This operation is not supported.

Reading

GET /{ig-media-id}/insights

Get insights data on an IG Media object. Values for each metric are calculated at the time of the request.

Limitations

Insights data is not available for any IG Media within an album IG Media.
Story IG Media insights are only available for 24 hours, even if the stories are archived or highlighted. If you want to get the latest insights for a story before it expires, set up a Webhook for the Instagram topic and subscribe to the story_insights field.
Story IG Media metrics with values less than 5 will return an error code 10 with the message (#10) Not enough viewers for the media to show insights.
If insights data you are requesting does not exist or is currently unavailable the API will return an empty data set instead of 0 for individual metrics.

Requirements

Type Description

Type	Description
Access Tokens	User
Permissions	`instagram_basic` `instagram_manage_insights` `pages_read_engagement` `pages_show_list` If the app user was granted a role on the Page via the Business Manager, you will also need one of: `ads_management` `business_management`

Access Tokens

User

Permissions

instagram_basic
instagram_manage_insights
pages_read_engagement
pages_show_list

If the app user was granted a role on the Page via the Business Manager, you will also need one of:

ads_management
business_management

Request Syntax

GET https://graph.facebook.com/v10.0/{ig-media-id}/insights
  ?metric={metric}
  &access_token={access-token}

Query String Parameters

Parameter	Value
`{access-token}` Required String	The app user's User Access Token.
`{metric}` Required Comma-separated list	A comma-separated list of Metrics you want returned.

Metrics

Photo and Video Metrics

Metrics on media within an album are not supported, get metrics on the album instead.

Metric	Description
`engagement`	Sum of `likes_count`, `comment_count` and `saved` counts on the IG Media.
`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.
`saved`	Total number of unique Instagram accounts that have saved the IG Media object.
`video_views`	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.

Album Metrics

Metric	Description
`carousel_album_engagement`	Total number of likes and IG Comments on the album IG Media object.
`carousel_album_impressions`	Total number of times the album IG Media object has been seen.
`carousel_album_reach`	Total number of unique Instagram accounts that have seen the album IG Media object.
`carousel_album_saved`	Total number of unique Instagram accounts that have saved the album IG Media object.
`carousel_album_video_views`	(Video IG Media objects only) Always returns 0. Use `carousel_album_reach` and `carousel_album_impressions` instead.

Story Metrics

Metric	Description
`exits`	Number of times someone exited the story IG Media object.
`impressions`	Total number of times the story IG Media object has been seen.
`reach`	Total number of unique Instagram accounts that have seen the story IG Media object.
`replies`	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 `0`.
`taps_forward`	Total number of taps to see this story IG Media object's next photo or video.
`taps_back`	Total number of taps to see this story IG Media object's previous photo or video.

Sample Request

curl -X GET \
  'https://graph.facebook.com/v10.0/17895695668004550/insights?metric=impressions,reach&access_token=IGQVJ...'

Sample Response

{
  "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"
    }
  ]
}

Updating

This operation is not supported.

Deleting

This operation is not supported.