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 /v19.0/{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 */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{page-id}?fields=instant_articles_insights.metric(metric-name)',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* 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();

/* 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_insightspermission can retrieve metrics for that Page. For more information on page access tokens, refer to our Page Access Tokens documentation.

Parameters

Name	Description	Type	Required
`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:

Name Description Type

Name	Description	Type
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>`

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.

Name	Description	Value 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 /v19.0/{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 /v19.0/{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 /v19.0/{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>"
}