Insights API

The Insights API is a subset of Instagram Graph API endpoints that allow you to get metrics about your Instagram Business Account.

Starting April 23rd, 2018, GET requests on the /user/insights edge will include ad activity generated through the API, Facebook ads interfaces, and Instagram's Promote feature. This affects the reach and impressions metrics.

Endpoints

The API consists of the following endpoints:

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

Common Uses

Getting an Account's Reach, Impressions, and Profile Views

You can use the Insights API to get your business account's reach, impressions, and profile_views metrics.

Sample Request

GET graph.facebook.com
  instagram_business_account_id/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 this profile has been seen",
      "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 unique accounts that have seen this profile",
      "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 unique accounts that have viewed this profile within the specified period",
      "id": "instagram_business_account_id/insights/profile_views/day"
    }
  ]
}

Getting Media Object Engagement, Impressions, and Reach

You can use the Insights API to get metrics about a specific business account post. The following example returns the reach, impressions, and profile_views metrics.

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

Limitations

  • We only store 2 years worth of metrics data.
  • You can only get insights for a single Instagram Business account 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.