Instagram User Insights

Represents social interaction metrics on an Instagram User, your app user's Instagram professional account.

Creating

This operation is not supported.

Reading

GET /<YOUR_APP_USERS_IG_USER_ID>/insights

Returns insights on an IG User, your app user's Instagram professional account.

Limitations

• follower_count and online_followers 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.
• Only viewers for whom we have demographic data are used in demographic metric calculations.
• Summing demographic metric values may result in a value less than the follower count (see previous bullet point).
• Data used to calculate metrics may be delayed up to 48 hours.

Requirements

Request Syntax

GET https://graph.facebook.com/v21.0/<YOUR_APP_USERS_IG_USER_ID>/insights
  ?metric=<COMMA_SEPARATED_LIST_OF_METRICS>
  &period=<PERIOD>
  &since=<START_TIME>
  &until=<STOP_TIME>
  &access_token=<INSTAGRAM_USER_ACCESS_TOKEN>

Path Parameters

Query String Parameters

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.

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/v21.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.

New Metrics

Request Syntax

GET https://graph.facebook.com/{api-version}/{ig-user-id}/insights
  ?metric=<COMMA_SEPARATED_LIST_OF_METRICS>
  &period=<PERIOD>
  &timeframe={timeframe}
  &metric_type={metric-type}
  &breakdown={breakdown}
  &since=<START_TIME>
  &until=<STOP_TIME>
  &access_token=<INSTAGRAM_USER_ACCESS_TOKEN>

Path Parameters

Query String Parameters

Breakdown

If you request metric_type=total_value, you can also specify one or more breakdowns, and the results will be broken down into smaller sets based on the specified breakdown. Values can be:

• contact_button_type — Break down results by profile UI component that viewers tapped or clicked. Response values can be:
  • BOOK_NOW
  • CALL
  • DIRECTION
  • EMAIL
  • INSTANT_EXPERIENCE
  • TEXT
  • UNDEFINED
• follow_type — Break down results by followers or non-followers. Response values can be:
  • FOLLOWER
  • NON_FOLLOWER
  • UNKNOWN
• media_product_type — Break down results by the surface where viewers viewed or interacted with the app user's media. Response values can be:
  • AD
  • FEED
  • REELS
  • STORY

Refer to the Metrics table to determine which metrics are compatible with a breakdown. If you request a metric that doesn't support a breakdown, the API will return an error ("An unknown error has occurred."), so be careful if requesting multiple metrics in a single query.

If you request metric_type=time_series, breakdowns will not be included in the response.

Metric Type

You can designate how you want results aggregated, either by time period or as a simple total (with breakdowns, if requested). Values can be:

• time_series — Tells the API to aggregate results by time period. See Period.
• total_value — Tells the API to return results as a simple total. If breakdowns are included in the request, the result set will be further broken down by the specific breakdowns. See Breakdown.

Period

Tells the API which time frame to use when aggregating results. Only compatible with interaction-related metrics.

Timeframe

Tells the API how far to look back for data when requesting demographic-related metrics. This value overrides the since and until parameters.

Range

Assign UNIX timestamps to the since and until parameters to define a range. The API will only include data created within this range (inclusive). If you do not include these parameters, the API will look back 24 hours.

For demographics-related metrics, the timeframe parameter overrides these values. See Timeframe.

Metrics

Interaction Metrics

Demographic Metrics

Response

A JSON object containing the results of your query. Results can include the following data, based on your query specifications:

{
  "data": [
    {
      "name": "{data}",
      "period": "<PERIOD>",
      "title": "{title}",
      "description": "{description}",
      "total_value": {
        "value": {value},
        "breakdowns": [
          {
            "dimension_keys": [
              "{key-1}",
              "{key-2",
              ...
            ],
            "results": [
              {
                "dimension_values": [
                  "{value-1}",
                  "{value-2}",
                  ...
                ],
                "value": {value},
                "end_time": "{end-time}"
              },
              ...
            ]
          }
        ]
      },
      "id": "{id}"
    }
  ],
  "paging": {
    "previous": "{previous}",
    "next": "{next}"
  }
}

Response Contents

Sample Interaction Metric Request

curl -i -X GET \
  "https://graph.facebook.com/v21.0/17841405822304914/insights?metric=reach&period=day&breakdown=media_product_type&metric_type=total_value&since=1658991600&access_token=EAAOc..."

Sample Interaction Metric Response

{
  "data": [
    {
      "name": "reach",
      "period": "day",
      "title": "Accounts reached",
      "description": "The number of unique accounts that have seen your content, at least once, including in ads. Content includes posts, stories, reels, videos and live videos. Reach is different from impressions, which may include multiple views of your content by the same accounts. This metric is estimated and in development.",
      "total_value": {
        "value": 224,
        "breakdowns": [
          {
            "dimension_keys": [
              "media_product_type"
            ],
            "results": [
              {
                "dimension_values": [
                  "CAROUSEL_CONTAINER"
                ],
                "value": 100
              },
              {
                "dimension_values": [
                  "POST"
                ],
                "value": 124
              }
            ]
          }
        ]
      },
      "id": "17841405309211844/insights/reach/day"
    }
  ],
  "paging": {
    "previous": "https://graph.face...",
    "next": "https://graph.face..."
  }

Sample Demographic Metric Request

curl -i -X GET \
  "https://graph.facebook.com/v21.0/17841405822304914/insights?metric=engaged_audience_demographics&period=lifetime&timeframe=last_90_days&breakdowns=country&metric_type=total_value&access_token=EAAOc..."

Sample Demographic Metric Response

{
  "data": [
    {
      "name": "engaged_audience_demographics",
      "period": "lifetime",
      "title": "Engaged audience demographics",
      "description": "The demographic characteristics of the engaged audience, including countries, cities and gender distribution.",
      "total_value": {
        "breakdowns": [
          {
            "dimension_keys": [
              "timeframe",
              "country"
            ],
            "results": [
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "AR"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "RU"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "MA"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "LA"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "IQ"
                ],
                "value": 2
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "MX"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "FR"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "ES"
                ],
                "value": 3
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "NL"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "TR"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "US"
                ],
                "value": 7
              }
            ]
          }
        ]
      },
      "id": "17841401130346306/insights/engaged_audience_demographics/lifetime"
    }
  ]
}