Insights

This edge allows you to get Instagram Business User insights.

Creating

This operation is not supported.

Reading

Getting Account Insights

To get insights for an Instagram Business User, 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. Amounts for each metric are calculated upon request.

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 User's followers. Does not include current day's data.

audience_country

lifetime

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

audience_gender_age

lifetime

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

audience_locale

lifetime

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

email_contacts

day

Total number of taps on the email link in the Business User'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 User's profile.

impressions

day, week, days_28

Total number of times the Business User'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 User's followers who were online during the specified range.

phone_call_clicks

day

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

profile_views

day

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

reach

day, week, days_28

Total number of times the Business User'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 User's profile.

website_clicks

day

Total number of taps on the website link in the Business User'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.