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.
This endpoint is comprised of the page ID and the metric that is being looked up. All available metrics are listed below.
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
}];
read_insights
permission can retrieve metrics for that Page. For more information on page access tokens, refer to our Page Access Tokens documentation. Name | Description | Type | Required |
---|---|---|---|
| Page ID. |
|
|
| Metric being requested. | See available metrics below |
|
| Period of time over which the metric is aggregated. |
|
|
| Lower bound of the time range to consider. Default value: |
|
|
| Upper bound of the time range to consider. Default value: |
|
|
| Separate results by which platform (iOS or Android) that the metric occured on. If not specified, results include both platforms. |
|
|
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 |
---|---|---|
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> |
Below are the aggregation periods available for different metrics. Metrics are gathered from both iOS and Android devices.
Name | Description | Value for period |
---|---|---|
| Number of views |
|
| Duration of view with breakdowns |
|
| Average duration of view |
|
| Scroll depth with breakdowns |
|
| Average scroll depth |
|
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>" }
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>" }
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>" }