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.
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.
GET /v21.0/?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();
/* 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
}];
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 |
---|---|---|---|
| Canonical URL of the Instant Article. |
|
|
| 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 one of your Instant Articles over the past 7 days, issue the following GET
request:
GET /v21.0/?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" }
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 /v21.0/?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" }
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 /v21.0/?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" }