Insights

Represents social interaction metrics on an IG Media object.

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 IG Media objects within album IG Media objects.
  • Story IG Media object 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 object metrics with values less than 5 will return a value of -1.

Requirements

TypeDescription

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/v7.0/{ig-media-id}/insights
  ?metric={metric}
  &access_token={access-token}

Query String Parameters

ParameterValue

{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

MetricDescription

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.

saved

Total number of unique Instagram accounts that have saved the IG Media object.

video_views

(Video IG Media objects only) Total number of times the video has been seen. Returns 0 for videos in an album IG Media object.

Album Metrics

MetricDescription

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

MetricDescription

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.

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.instagram.com/v7.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.