Instagram Platform API account IDs will not work with the new Instagram Graph API. Please use the Page node to determine the correct Instagram Business Account ID associated with the Facebook page.

Insights

This edge allows you to get an insights for an 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.

Creating

This operation is not supported.

Reading

Getting Account Insights

To get insights for an Instagram Business Account, send a GET request to the /user/insights edge and include the metric parameter with one or more metrics, as well as the period parameter and a timeframe (e.g. daily impressions or weekly impressions).

Permissions

A User access token with the following permissions:

  • instagram_basics
  • instagram_manage_insights
  • manage_pages

Metrics and Periods

We support the following metrics. Requests must include both the metric and period parameters. Use metric to specify the metric you want returned, and period to specify a timeframe.

Starting April 23rd, 2018, the reach and impressions metrics will include ad activity generated through the API, Facebook ads interfaces, and Instagram's Promote feature.

MetricCompatible PeriodDescription

audience_city

lifetime

The cities of the Business Account's followers. Does not include current day's data.

audience_country

lifetime

The countries of the Business Account's followers. Does not include current day's data.

audience_gender_age

lifetime

The gender and age distribution of the Business Account's followers. Does not include current day's data.

audience_locale

lifetime

The locales by country codes of the Business Account's followers. Does not include current day's data.

email_contacts

day

Total number of taps on the email link in the Business Account's profile.

follower_count

day

Total number of unique users following the Business Account.

get_directions_clicks

day

Total number of taps on the directions link in the Business Account's profile.

impressions

day, week, days_28

Total number of times the Business Account's media objects (i.e. posts, stories and promotions) have been viewed. Does not include profile views.

online_followers

lifetime

Total number of the Business Account's followers who were online during the specified period.

phone_call_clicks

day

Total number of taps on the call link in the Business Account's profile.

profile_views

day

Total number of unique users who have viewed the Business Account's profile within the specified period.

reach

day, week, days_28

Total number of unique users who have viewed the Business Account's profile.

text_message_clicks

day

Total number of taps on the text message link in the Business Account's profile.

website_clicks

day

Total number of taps on the website link in the Business Account's profile.

Time-Based Pagination

This edge supports time-based pagination, so you can include the since and until parameters with Unix timestamps to define a range. For example, to get 28 days worth of impressions — every day for the last 10 days — you could generate Unix timestamps for 10 days ago and today, assign them to the since and until parameters, and include them in your request:

metric=impressions&period=days_28&since=1501545600&until=1502493720

The since and until parameters are inclusive, so if your range includes a day that hasn't ended (i.e, today), subsequent queries throughout the day may return increased values. If you do not include the since and until parameters, the API will default to a 2 day range: yesterday through today.

Sample Request

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

Sample Response

Notice that the sample request above did not include the since and until parameters, so the API returned data for a default range of 2 days. Each day is identified by an ISO 8601 formatted date, which has been assigned to an end_time property.

{
  "data": [
    {
      "name": "impressions",
      "period": "day",
      "values": [
        {
          "value": 4,
          "end_time": "2017-05-04T07:00:00+0000"
        },
        {
          "value": 66,
          "end_time": "2017-05-05T07:00:00+0000"
        }
      ],
      "title": "Impressions",
      "description": "Total number of times this profile has been seen",
      "id": "17841400008460056/insights/impressions/day"
    },
    {
      "name": "reach",
      "period": "day",
      "values": [
        {
          "value": 3,
          "end_time": "2017-05-04T07:00:00+0000"
        },
        {
          "value": 36,
          "end_time": "2017-05-05T07:00:00+0000"
        }
      ],
      "title": "Reach",
      "description": "Total number of unique accounts that have seen this profile",
      "id": "17841400008460056/insights/reach/day"
    },
    {
      "name": "profile_views",
      "period": "day",
      "values": [
        {
          "value": 0,
          "end_time": "2017-05-04T07:00:00+0000"
        },
        {
          "value": 2,
          "end_time": "2017-05-05T07:00:00+0000"
        }
      ],
      "title": "Profile Views",
      "description": "Total number of unique accounts that have viewed this profile within the specified period",
      "id": "17841400008460056/insights/profile_views/day"
    }
  ]
}

Updating

This operation is not supported.

Deleting

This operation is not supported.