Graph API Version

Insights Metrics of Aggregated Instant Articles

This object represents the set of insights metrics aggregated across all Instant Articles that have been published by a Facebook Page. For more information on Instant Articles, read our Instant Articles Developer Documentation.

These insights include any sharing of the Instant Article within Facebook and are not limited to only posts from its Page.

Data for these insights are only available since November 30, 2015.

Reading

This endpoint is comprised of the page ID and the metric that is being looked up. All available metrics are listed below.

Graph API Explorer
GET /v2.9/{page-id}?fields=instant_articles_insights.metric(metric-name) HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{page-id}?fields=instant_articles_insights.metric(metric-name)'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{page-id}?fields=instant_articles_insights.metric(metric-name)",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{page-id}?fields=instant_articles_insights.metric(metric-name)",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{page-id}?fields=instant_articles_insights.metric(metric-name)"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • A page access token with the read_insights permission can retrieve metrics for that Page. For more information on page access tokens, refer to our Page Access Tokens documentation.

Parameters

NameDescriptionTypeRequired

id

Page ID.

string

yes

metric

Metric being requested.

See available metrics below

yes

period

Period of time over which the metric is aggregated.

enum{day, week, days_28, month, lifetime}

yes

since

Lower bound of the time range to consider. Default value: 2 weeks ago

datetime

no

until

Upper bound of the time range to consider. Default value: Current time

datetime

no

breakdown

Separate results by which platform (iOS or Android) that the metric occured on. If not specified, results include both platforms.

enum{platform}

no

Fields

Reading from this edge will return a JSON formatted result:

{
  "data": []
}

data

A list of InsightsQueryResult objects. The following fields will be added to each object that is returned:

NameDescriptionType

time

The start of the period, or the end time of lifetime period.

datetime

value

The metric's count, average, ratio or percentage in the period.

numeric

breakdowns

The bucket that the value belongs to (i.e. when the all_view_durations metric is used or if the breakdown(platform) parameter is explicitely specified).

map<string, string>

Available Metrics

Below are the aggregation periods available for different metrics. Metrics are gathered from both iOS and Android devices.

NameDescriptionValue for period

all_views

Number of views

day

all_view_durations

Duration of view with breakdowns

week

all_view_durations_average

Average duration of view

week

all_scrolls

Scroll depth with breakdowns

week

all_scrolls_average

Average scroll depth

week

Examples

Daily article views over the last 7 days

To query daily breakdowns of the number of views of all of the Instant Articles from your Page over the past 7 days, issue the following GET request:

GET /v2.9/{page-id}?fields=instant_articles_insights.metric(all_views).period(day).since(7 day ago).until(now)&access_token={your-page-access-token} HTTP/1.1
Host: graph.facebook.com

This request will return the following response:

{
   "instant_articles_insights": {
      "data": [
        {
          "time": "2015-11-30T08:00:00+0000",
          "value": "224067"
        },
        {
          "time": "2015-12-01T08:00:00+0000",
          "value": "467846"
        },
        {
          "time": "2015-12-02T08:00:00+0000",
          "value": "849467"
        },
        {
          "time": "2015-12-03T08:00:00+0000",
          "value": "188502"
        },
        {
          "time": "2015-12-04T08:00:00+0000",
          "value": "321942"
        },
        {
          "time": "2015-12-05T08:00:00+0000",
          "value": "622841"
        },
        {
          "time": "2015-12-06T08:00:00+0000",
          "value": "198124"
        }
      ]
   },
   "id": "<page-id>"
}

Daily article views over the last 7 days with platform breakdown

To query daily breakdowns of the number of views of all of the Instant Articles from your Page over the past 7 days, further broken down by the platform it was viewed on, issue the following GET request:

GET /v2.9/{page-id}?fields=instant_articles_insights.metric(all_views).breakdown(platform).period(day).since(7 day ago).until(now)&access_token={your-page-access-token} HTTP/1.1
Host: graph.facebook.com

This request will return the following response:

{
   "instant_articles_insights": {
      "data": [
        {
          "time": "2015-11-30T08:00:00+0000",
          "value": "112033",
          "breakdowns": {
            "platform": "ANDROID"
          }
        },
        {
          "time": "2015-11-30T08:00:00+0000",
          "value": "112034",
          "breakdowns": {
            "platform": "IOS"
          }
        },
        {
          "time": "2015-12-01T08:00:00+0000",
          "value": "233923",
          "breakdowns": {
            "platform": "ANDROID"
          }
        },
        {
          "time": "2015-12-01T08:00:00+0000",
          "value": "233923",
          "breakdowns": {
            "platform": "IOS"
          }
        },
        {
          "time": "2015-12-02T08:00:00+0000",
          "value": "424733",
          "breakdowns": {
            "platform": "ANDROID"
          }
        },
        {
          "time": "2015-12-02T08:00:00+0000",
          "value": "424734",
          "breakdowns": {
            "platform": "IOS"
          }
        }
      ]
   },
   "id": "<page-id>"
}

Weekly article scroll depths over the last 7 days

To query weekly breakdowns of the bucketed scroll depths of all of the Instant Articles from your Page over the past 7 days, issue the following GET request:

GET /v2.9/{page-id}?fields=instant_articles_insights.metric(all_scrolls).period(week).since(7 day ago).until(now)&access_token={your-page-access-token} HTTP/1.1
Host: graph.facebook.com

This request will return the following response. Note that the data returned in this response is bucketed. Visitors within the requested window are returned via value and scroll depth percentages via bucket:

{
   "instant_articles_insights": {
    "data": [
      {
        "time": "2015-11-26T08:00:00+0000",
        "value": "334606",
        "breakdowns": {
          "bucket": "100"
        }
      },
      {
        "time": "2015-11-26T08:00:00+0000",
        "value": "27339",
        "breakdowns": {
          "bucket": "94"
        }
      },
      {
        "time": "2015-11-26T08:00:00+0000",
        "value": "26746",
        "breakdowns": {
          "bucket": "95"
        }
      },
      {
        "time": "2015-11-26T08:00:00+0000",
        "value": "26727",
        "breakdowns": {
          "bucket": "93"
        }
      },
      {
        "time": "2015-11-26T08:00:00+0000",
        "value": "26512",
        "breakdowns": {
          "bucket": "96"
        }
      }
     ]
   }, 
   "id": "<page-id>"
}