Insights

Represents social interaction metrics on an IG User.

Creating

This operation is not supported.

Reading

Getting Account Insights

GET /{ig-user-id}/insights?metric={metric}&period={period}&since={since}&until={until}

Returns insights on an IG User. Metric values are calculated upon request.

Query String Parameters

Query string parameters are optional unless indicated as required.

  • {metric} (required) — A comma-separated list of metrics you want returned. See Metrics and Periods.
  • {period} (required) — Specifies an aggregation period. See Metrics and Periods.
  • {since} — Used in conjunction with {until} to define a range.
  • {until} — Used in conjunction with {since} to define 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 Facebook User access token with the following permissions:

  • instagram_basic
  • instagram_manage_insights
  • manage_pages or pages_show_list

Metrics and Periods

MetricCompatible PeriodDescription

audience_city

lifetime

The cities of the IG User's followers. Does not include current day's data.

audience_country

lifetime

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

audience_gender_age

lifetime

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

audience_locale

lifetime

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

email_contacts

day

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

impressions

day, week, days_28

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

phone_call_clicks

day

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

profile_views

day

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

reach

day, week, days_28

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

website_clicks

day

Total number of taps on the website link in the IG User's profile.

Defining a Range

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.