Insights

This guide shows you how to get insights for your app users' Instagram media and professional accounts using the Instagram Platform.

In this guide we will be using Instagram user and Instagram professional account interchangeably. An Instagram User object represents your app user's Instagram professional account.

Before you start

You will need the following:

Requirements

Access Level

• Advanced Access if your app serves Instagram professional accounts you don't own or manage
• Standard Access if your app serves Instagram professional accounts you own or manage and have added to your app in the App Dashboard

Endpoints

• GET /<INSTAGRAM_MEDIA_ID>/insights — Gets metrics on a media object
• GET /<INSTAGRAM_ACCOUNT_ID>/insights — Gets metrics on an Instagram Business Account or Instagram Creator account.

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

UTC

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

Webhook event subscriptions

• story_insights – Only available for Instagram API with Facebook Login.

Limitations

Media insights

Account insights

Examples

Instagram account request

The following Instagram API with Facebook Login example is getting the number of impressions, profile_views, and reach for your app user's Instagram professional account over one 24 hour period.

To get metrics for an Instagram business or creator account, query the GET /<INSTAGRAM_USER_ID>/insights endpoint with the metrics parameter set to a comma-separated list of the metrics, impressions, profile_views, and reach, and the period set to day.

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

Sample Response

On success, your app receives an array for each metric that includes, the metric description, ID of the metric, name and title, the time period over which the metric was measured, and values of the metric.

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

Instagram media request

The following Instagram API with Instagram Login example is getting the number of engagement, impressions, and reach for your app user's Instagram media over one 24 hour period.

To get metrics for an Instagram business or creator account's media, query the GET /<INSTAGRAM_MEDIA_ID>/insights endpoint with the metrics parameter set to a comma-separated list of the metrics, engagement, impressions, and reach, and the period set to day.

GET graph.instagram.com/17841491440582230/insights
    ?metric=engagement,impressions,reach

Sample Response

On success, your app receives an array for each metric that includes, the metric description, ID of the metric, name and title, the time period over which the metric was measured, and values of the metric.

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

Next Steps

Visit the API Reference to see all available metrics for Instagram business and creator accounts and their Instagram Media objects.