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 insights for an Instagram Business Account.

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 and period parameters, and optionally, the since and until parameters. Use metric to specify a metric, period to specify an aggregation period, and since and until to specify a range.

For example, to get total impressions (metric) for a one week period of time (aggregation period), every day for a 10 day range (range), you would do this:

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

If you do not include the since and until parameters, the API will default to a 2 day range: yesterday through today.

Permissions

A User access token with the following permissions:

  • instagram_basics
  • instagram_manage_insights
  • manage_pages

Metrics and Periods

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 new followers each day within the specified range.

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. Includes ad activity generated through the API, Facebook ads interfaces, and the Promote feature. Does not include profile views.

online_followers

lifetime

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

phone_call_clicks

day

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

profile_views

day

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

reach

day, week, days_28

Total number of times the Business Account's media objects (i.e. posts, stories and promotions) have been uniquely viewed. Includes ad activity generated through the API, Facebook ads interfaces, and the Promote feature.

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.