Instagram Graph API

IG User Insights

Represents social interaction metrics on an IG User.

Creating

This operation is not supported.

Reading

GET /{ig-user-id}/insights

Returns insights on an IG User.

Limitations

  • follower_count, online_followers, and all audience_* metrics are not available on IG Users with fewer than 100 followers.
  • Insights data for the online_followers metric is only available for the last 30 days.
  • If insights data you are requesting does not exist or is currently unavailable the API will return an empty data set instead of 0 for individual metrics.
  • Demographic metrics only return the top 45 performers (e.g., for audience_city, up to 45 cities with the highest number of followers can be returned).
  • Only followers for whom we have demographic data are used in demographic metric calculations.
  • Summing demographic metric values may result in a value less than follower count (see previous bullet point).
  • audience_* metrics do not support since and until range parameters.
  • Data used to calculate metrics may be delayed up to 48 hours.

Requirements

TypeDescription

Access Tokens

User

Permissions

instagram_basic
instagram_manage_insights
pages_read_engagement
pages_show_list


If the app user was granted a role on the Page via the Business Manager, you will also need one of:


ads_management
business_management

Request Syntax

GET https://graph.facebook.com/v12.0/{ig-user-id}/insights
  ?metric={metric}
  &period={period}
  &since={since}
  &until={until}
  &access_token={access-token}

Query String Parameters

ParameterValue

{access-token}
Required
String

The app user's User Access Token.

{metric}
Required
Comma-separated list

A comma-separated list of Metrics you want returned. If requesting multiple metrics, they must all have the same compatible Period.

{period}
Required
String

A Period that is compatible with the metrics you are requesting.

{since}
Unix timestamp

Used in conjunction with {until} to define a Range. If you omit since and until, the API defaults to a 2 day range: yesterday through today.


Note: The pagination cursors (previous and next) fetch the next time window of results, not the next batch of results within the current time window.

{until}
Unix timestamp

Used in conjunction with {since} to define a Range. If you omit since and until, the API defaults to a 2 day range: yesterday through today.


Note: The pagination cursors (previous and next) fetch the next time window of results, not the next batch of results within the current time window.

Metrics and Periods

Metrics that support lifetime periods will have results returned in an array of 24 hour periods, with periods ending on UTC−07:00. audience_* metrics do not support since and until range parameters.

MetricCompatible PeriodDescription

audience_city

lifetime

Cities of followers for whom we have demographic data. Does not include current day's data. Not available on IG Users with fewer than 100 followers. Only top 45 cities with highest values returned.

audience_country

lifetime

Countries of followers for whom we have demographic data. Does not include current day's data. Not available on IG Users with fewer than 100 followers. Only top 45 countries with highest values returned.

audience_gender_age

lifetime

The gender and age distribution of followers for whom we have demographic data. Does not include current day's data. Not available on IG Users with fewer than 100 followers. Possible values: M (male), F (female), U (unknown).

audience_locale

lifetime

Locales by country codes of followers for whom we have demographic data. Does not include current day's data. Not available on IG Users with fewer than 100 followers. Only top 45 locales with highest values returned.

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. Returns a maximum of 30 days worth of data. Not available on IG Users with fewer than 100 followers.

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 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. Not available on IG Users with fewer than 100 followers.

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 unique users who have viewed at least one of the IG User's IG Media. Repeat views and views across different IG Media owned by the IG User by the same user are only counted as a single view. 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.

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

curl -X GET \
  'https://graph.facebook.com/v12.0/17841405822304914/insights?metric=impressions,reach,profile_views&period=day&access_token=IGQVJ...'

Sample Response

{
  "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"
    }
  ]
}

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 UTC timestamp with zero offset, which has been assigned to an end_time property.

The end_time property indicates a data set's lookback cutoff date; data older than this value is not included in the data set's calculation.

Updating

This operation is not supported.

Deleting

This operation is not supported.