Insights API

The Insights API allows you to get metrics for Instagram Business Accounts and the media objects they own. Amounts for each metric are calculated upon request.

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.

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 a Business User's Reach, Impressions, and Profile Views

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

Sample Request

GET graph.facebook.com/{instagram-business-user-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 business user posts. The following example returns the reach, impressions, and profile_views metrics.

Sample Request

GET graph.facebook.com/{instagram-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"
    }
  ]
}