Insights

You can use the Instagram Graph API to get social interaction metrics for IG Users and their IG Media objects. Amounts for each metric are calculated upon API request.

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.

Limitations

  • Some metrics are not available on IG Users with fewer than 100 followers.
  • The API only reports organic interaction metrics; interactions on ads containing a media object are not counted.
  • Media metrics data is stored for up to 2 years. User Metrics data is stored for up to 90 days.
  • You can only get insights for a single user at a time.
  • You cannot get insights for Facebook Pages.
  • Stories 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.
  • Insights on album child IG Media is not supported.
  • 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.

UTC

Timestamps in API responses use UTC with zero offset and are formatted using ISO-8601. For example: 2019-04-05T07:56:32+0000

Endpoints

The API consists of the following endpoints:

Refer to each endpoint's reference documentation for available metrics, parameters, and permission requirements.

Examples

Getting Account Metrics

To get metrics on an Instagram Business or Creator Account, query the GET /{ig-user-id}/insights edge and specify the metrics you want returned.

Sample Request

GET graph.facebook.com/17841405822304914/insights
    ?metric=impressions,reach,profile_views
    &period=day

Sample Response

{
  "data": [
    {
      "name": "impressions",
      "period": "day",
      "values": [
        {
          "value": 32,
          "end_time": "2018-01-11T08:00:00+0000"
        },
        {
          "value": 32,
          "end_time": "2018-01-12T08:00:00+0000"
        }
      ],
      "title": "Impressions",
      "description": "Total number of times the Business Account's media objects have been viewed",
      "id": "instagram_business_account_id/insights/impressions/day"
    },
    {
      "name": "reach",
      "period": "day",
      "values": [
        {
          "value": 12,
          "end_time": "2018-01-11T08:00:00+0000"
        },
        {
          "value": 12,
          "end_time": "2018-01-12T08:00:00+0000"
        }
      ],
      "title": "Reach",
      "description": "Total number of times the Business Account's media objects have been uniquely viewed",
      "id": "instagram_business_account_id/insights/reach/day"
    },
    {
      "name": "profile_views",
      "period": "day",
      "values": [
        {
          "value": 15,
          "end_time": "2018-01-11T08:00:00+0000"
        },
        {
          "value": 15,
          "end_time": "2018-01-12T08:00:00+0000"
        }
      ],
      "title": "Profile Views",
      "description": "Total number of users who have viewed the Business Account's profile within the specified period",
      "id": "instagram_business_account_id/insights/profile_views/day"
    }
  ]
}

Getting Media Metrics

To get metrics on a media object, query the GET /{ig-media-id}/insights edge and specify the metrics you want returned.

Sample Request

GET graph.facebook.com/{media-id}/insights
    ?metric=engagement,impressions,reach

Sample Response

{
  "data": [
    {
      "name": "engagement",
      "period": "lifetime",
      "values": [
        {
          "value": 8
        }
      ],
      "title": "Engagement",
      "description": "Total number of likes and comments on the media object",
      "id": "media_id/insights/engagement/lifetime"
    },
    {
      "name": "impressions",
      "period": "lifetime",
      "values": [
        {
          "value": 13
        }
      ],
      "title": "Impressions",
      "description": "Total number of times the media object has been seen",
      "id": "media_id/insights/impressions/lifetime"
    },
    {
      "name": "reach",
      "period": "lifetime",
      "values": [
        {
          "value": 13
        }
      ],
      "title": "Reach",
      "description": "Total number of unique accounts that have seen the media object",
      "id": "media_id/insights/reach/lifetime"
    }
  ]
}