Graph API Version

Insights Metrics for Instant Article

This object represents the set of insights metrics for a single Instant Article, based on its canonical URL. Article-level metrics can be queried, as well as metrics on individual media assets within the article.

For more information on Instant Articles, read our Instant Articles Developer Documentation.

Article Insights

The endpoint used to query article-level insights is determined by the canonical URL of the article being queried and the metric that is being looked up. All available metrics are listed below.

Graph API Explorer
GET /v2.11/?fields=instant_article{insights.metric(metric-name)}&id={canonical-url} 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(
    '/?fields=instant_article{insights.metric(metric-name)}&id={canonical-url}',
    '{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(
    "/?fields=instant_article{insights.metric(metric-name)}&id={canonical-url}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/?fields=instant_article{insights.metric(metric-name)}&id={canonical-url}",
    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:@"/?fields=instant_article{insights.metric(metric-name)}&id={canonical-url}"
                                      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

Canonical URL of the Instant Article.

url

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

Video Insights

The endpoint used to query Instant Articles video-level insights is determined by the canonical URL of the article being queried and the metric that is being looked up. All available metrics are listed below.

Graph API Explorer
GET /v2.11/?fields=instant_article{videos{video,insights.metric(metric-name)}}&id={canonical-url} 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(
    '/?fields=instant_article{videos{video,insights.metric(metric-name)}}&id={canonical-url}',
    '{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(
    "/?fields=instant_article{videos{video,insights.metric(metric-name)}}&id={canonical-url}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/?fields=instant_article{videos{video,insights.metric(metric-name)}}&id={canonical-url}",
    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:@"/?fields=instant_article{videos{video,insights.metric(metric-name)}}&id={canonical-url}"
                                      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

Canonical URL of the Instant Article.

url

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

Fields

Reading from this edge will return a JSON formatted result containing a list of videos included in the Instant Article, with a list of InsightsQueryResult objects exposed through the data field on each video object.

data

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

NameDescriptionType

name

The name of the requested metric.

string

period

Period of time over which the metric is aggregated.

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

values

List of values for each aggregation of this metric.

map<string, string>

title

The title of this metric.

string

description

A description of this metric.

string

id

FBID of the video.

numeric string

Available Metrics

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

NameDescriptionValue for period

video_views

Total number of times your video was viewed for more than 3 seconds.

lifetime, day

video_views_autoplayed

Number of times your video started automatically playing and people viewed it for more than 3 seconds.

lifetime

video_views_clicked_to_play

Number of times people clicked to play your video and viewed it more than 3 seconds.

lifetime

video_views_unique

Total number of times your video was viewed for more than 3 seconds by unique users.

lifetime

video_views_sound_on

Number of times your video was viewed with sound on for 3 seconds or viewed to the end, whichever happened first.

lifetime

video_complete_views_30s

Total number of times video has been viewed for more than 30 seconds.

lifetime

video_complete_views_30s_unique

Total number of times video has been viewed by unique users for more than 30 seconds.

lifetime

video_complete_views_30s_autoplayed

Number of times your video started automatically playing and people viewed it for 30 seconds or to the end, whichever came first.

lifetime

video_complete_views_30s_clicked_to_play

Number of times people clicked to play your video and viewed it for 30 seconds or to the end, whichever came first.

lifetime

video_views_10s

Total number of times video has been viewed for more than 10 seconds.

lifetime

video_views_10s_unique

Number of unique viewers who watched your video for 10 seconds or to the end, whichever happened first.

lifetime

video_views_10s_autoplayed

Number of times your video started playing automatically and people viewed it for 10 seconds or to the end, whichever happened first.

lifetime

video_views_10s_clicked_to_play

Number of times people clicked to play your video and viewed it for 10 seconds or to the end, whichever happened first.

lifetime

video_views_10s_sound_on

Number of times your video was viewed with sound on for 10 seconds or viewed to the end, whichever happened first.

lifetime

video_retention_graph

Percentage of viewers at each interval. Video length is divided into short buckets. Each key in response represents a bucket. Values are percent of people saw the video in that bucket.

lifetime

video_retention_graph_autoplayed

Percentage of viewers at each interval where the video started playing automatically. Video length is divided into short buckets. Each key in response represents a bucket. Values are percent of people saw the video in that bucket.

lifetime

video_retention_graph_clicked_to_play

Percentage of viewers at each interval where people clicked to play your video. Video length is divided into short buckets. Each key in response represents a bucket. Values are percent of people saw the video in that bucket.

lifetime

video_avg_time_watched

The average length of time (in milliseconds) people spent viewing your video.

lifetime

video_view_time

Total time (in milliseconds) video has been viewed.

lifetime, day

video_views_by_country_id

Total number of times your video was viewed by viewers in various countries.

lifetime

video_views_by_age_bucket_and_gender

Total number of video views by Top Audience (Age and Gender).

lifetime

video_view_time_by_country_id

Video view time (in MS) by Top Location (Country).

lifetime

video_view_time_by_region_id

Video View Time (in MS) by Top Location (Region).

lifetime

video_view_time_by_age_bucket_and_gender

Video view time (in MS) by Top Audience (Age and Gender).

lifetime

Examples

Daily article views over the last 7 days

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

GET /v2.11/?fields=instant_article{insights.metric(all_views).period(day).since(7 day ago).until(now)}&id=http://www.example.com/my-test-page.html&access_token={your-page-access-token} HTTP/1.1
Host: graph.facebook.com

This request will return the following response:

{
   "instant_article": {
      "insights": {
         "data": [
            {
               "time": "2015-10-28T08:00:00+0000",
               "value": "3"
            },
            {
               "time": "2015-10-29T08:00:00+0000",
               "value": "3"
            },
            {
               "time": "2015-10-30T08:00:00+0000",
               "value": "3"
            },
            {
               "time": "2015-10-31T08:00:00+0000",
               "value": "3"
            },
            {
               "time": "2015-11-01T08:00:00+0000",
               "value": "2"
            },
            {
               "time": "2015-11-02T08:00:00+0000",
               "value": "6"
            },
            {
               "time": "2015-11-03T08:00:00+0000",
               "value": "4"
            }
         ]
      },
      "id": "<article-id>"
   },
   "id": "http://www.example.com/my-test-page.com"
}

Daily article views over the last 7 days with platform breakdown

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

GET /v2.11/?fields=instant_article{insights.metric(all_views).breakdown(platform).period(day).since(7 day ago).until(now)}&id=http://www.example.com/my-test-page.html&access_token={your-page-access-token} HTTP/1.1
Host: graph.facebook.com

This request will return the following response:

{
   "instant_article": {
      "insights": {
         "data": [
            {
              "time": "2015-10-28T08:00:00+0000",
              "value": "1",
              "breakdowns": {
                "platform": "ANDROID"
              }
            },
            {
              "time": "2015-10-28T08:00:00+0000",
              "value": "2",
              "breakdowns": {
                "platform": "IOS"
              }
            },
            {
              "time": "2015-10-29T08:00:00+0000",
              "value": "1",
              "breakdowns": {
                "platform": "ANDROID"
              }
            },
            {
              "time": "2015-10-29T08:00:00+0000",
              "value": "2",
              "breakdowns": {
                "platform": "IOS"
              }
            },
            {
              "time": "2015-10-30T08:00:00+0000",
              "value": "1",
              "breakdowns": {
                "platform": "ANDROID"
              }
            },
            {
              "time": "2015-10-30T08:00:00+0000",
              "value": "2",
              "breakdowns": {
                "platform": "IOS"
              }
            }
         ]
      },
      "id": "<article-id>"
   },
   "id": "http://www.example.com/my-test-page.com"
}

Weekly article view durations over the last 7 days

To query weekly breakdowns of the bucketed view durations of one of your Instant Articles over the past 7 days, issue the following GET request:

GET /v2.11/?fields=instant_article{insights.metric(all_view_durations).period(week).since(7 day ago).until(now)}&id=http://www.example.com/my-test-page.html&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:

{
   "instant_article": {
      "insights": {
         "data": [
            {
               "time": "2015-10-29T08:00:00+0000",
               "value": "8",
               "breakdowns": {
                  "bucket": "15"
               }
            },
            {
               "time": "2015-10-29T08:00:00+0000",
               "value": "2",
               "breakdowns": {
                  "bucket": "225"
               }
            },
            {
               "time": "2015-10-29T08:00:00+0000",
               "value": "2",
               "breakdowns": {
                  "bucket": "90"
               }
            },
            {
               "time": "2015-10-29T08:00:00+0000",
               "value": "1",
               "breakdowns": {
                  "bucket": "360"
               }
            },
            {
               "time": "2015-10-29T08:00:00+0000",
               "value": "1",
               "breakdowns": {
                  "bucket": "240"
               }
            },
            {
               "time": "2015-10-29T08:00:00+0000",
               "value": "1",
               "breakdowns": {
                  "bucket": "165"
               }
            },
            {
               "time": "2015-10-29T08:00:00+0000",
               "value": "1",
               "breakdowns": {
                  "bucket": "120"
               }
            },
            {
               "time": "2015-10-29T08:00:00+0000",
               "value": "1",
               "breakdowns": {
                  "bucket": "75"
               }
            },
            {
               "time": "2015-10-29T08:00:00+0000",
               "value": "1",
               "breakdowns": {
                  "bucket": "60"
               }
            },
            {
               "time": "2015-10-29T08:00:00+0000",
               "value": "1",
               "breakdowns": {
                  "bucket": "45"
               }
            },
            {
               "time": "2015-10-29T08:00:00+0000",
               "value": "1",
               "breakdowns": {
                  "bucket": "30"
               }
            }
         ]
      },
      "id": "<article-id>"
   },
   "id": "http://www.example.com/my-test-page.com"
}

Daily video view time

To query the daily video view time for one of your Instant Articles, issue the following GET request:

GET /v2.11/?fields=instant_article{videos{video,insights.metric(video_view_time)}}&id=canonical-url HTTP/1.1
Host: graph.facebook.com

This request will return the following response:

{
  "instant_article": {
    "videos": [
      {
        "video": {
          "updated_time": "2016-09-15T09:32:42+0000",
          "id": "1234"
        },
        "insights": {
          "data": [
            {
              "name": "video_view_time",
              "period": "day",
              "values": [
                {
                  "value": 1923,
                  "end_time": "2016-09-02T07:00:00+0000"
                },
                {
                  "value": 3224,
                  "end_time": "2016-09-03T07:00:00+0000"
                },
                {
                  "value": 168,
                  "end_time": "2016-09-04T07:00:00+0000"
                }
              ],
              "title": "Daily Total Video View Time (in MS)",
              "description": "Daily: Total time (in ms) video has been viewed",
              "id": "1234"
            },
          ],
        }
      }
    ],
    "id": "1234"
  },
  "id": "canonical-url"
}