This document refers to an outdated version of Graph API. Please use the latest version.
Graph API Version

Page Insights

/{object-id}/insights

Facebook Insights is a product available to all Pages and Apps on Facebook using the Insights dashboard. This object represents a single Insights metric that is tied to another particular Graph API object (Page, Post, etc.). This object is returned by the following edges:

Insights are only generated for a Facebook Page that has more than 100 people that like it. Likewise, demographic metrics, such as age, gender and location, are available in Page Insights once there is data for 100 or more people.

App Insights are now returned by a separate /app/app_insights edge and will no longer work with this edge in v2.1.

  • The Graph API object {post-id} needs to be specified in the same format returned by the API call to fetch a list of page posts - do not attempt to split or combine other IDs to form a post ID.
  • The Insights API only offers two years retention. Insights data older than two years is subject to removal.
  • Only 90 days of insights can be viewed at one time when using since and until parameters.
  • When using since and until, the since date data will be included in the first value returned.
  • If you neglect to indicate a specific metric or metrics for the endpoint, you will receive an error response such as:
{
  "error": {
    "message": "Invalid query",
    "type": "OAuthException",
    "code": 3001,
    "error_subcode": 1504028,
    "is_transient": false,
    "error_user_title": "No Metric Specified",
    "error_user_msg": "No metric was specified to be fetched. Please specify one or more metrics to be fetched and try again.",
    "fbtrace_id": "GpdspOgqUHT"
  }
}

Reading

The endpoint used is determined both by the object (Page, Post) being queried and the metric that is being looked up. All available metrics are listed below.

Permissions

A Page access token with read_insights permissions

Page Storytellers by Country

The data for page_storytellers_by_country contains data for the top 45 countries overall, not the top 45 countries for your page. This means:

  • If your page has no data for the overall top 45 countries, they will not appear in the list
  • If you have users that are not from the top 45 countries, they will not appear in the list

Therefore the sum of all breakdwon values returned by page_storytellers_by_country may not be the same value returned by page_storytellers.

Examples

There are two different ways to access the metrics of the Insights edge -- a single metric or a list of several metrics.

Single Metric

Graph API Explorer
GET v3.1/{object_id}/insights/{metric} 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(
    '{object_id}/insights/{metric}',
    '{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(
    "{object_id}/insights/{metric}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "{object_id}/insights/{metric}",
    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:@"{object_id}/insights/{metric}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
If you want to learn how to use the Graph API, read our Using Graph API guide.

Multiple Metrics

Graph API Explorer
GET v3.1/{object_id}/insights?metric={metric[,metric,...]} 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(
    '{object_id}/insights?metric={metric[,metric,...]}',
    '{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(
    "{object_id}/insights?metric={metric[,metric,...]}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "{object_id}/insights?metric={metric[,metric,...]}",
    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:@"{object_id}/insights?metric={metric[,metric,...]}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
If you want to learn how to use the Graph API, read our Using Graph API guide.

Insights Result Fields

The fields of the Insights result can be found here.

Parameters

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

The aggregation period

metric
list<A valid metric for an insights endpoint>

The list of metrics that needs to be fetched

since
datetime

Lower bound of the time range to consider

until
datetime

Upper bound of the time range to consider

show_description_from_api_doc
boolean
Default value: false

If set to true, then an additional description of the metric, retrieved from the API doc(https://developers.facebook.com/docs/graph-api/reference/insights) will be included in the retruned data

date_preset
enum{today, yesterday, last_3_days, this_week, last_week, last_7_days, last_14_days, last_28_days, last_30_days, last_90_days, this_month, last_month, this_quarter, last_3_months, lifetime}

Preset a date range, like lastweek, yesterday. If since or until presents, it does not work.

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {} }

data

A list of InsightsResult nodes.

paging

For more details about pagination, see the Graph API guide.

Creating

You can't perform this operation on this endpoint.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.

Available Metrics

All available metrics are shown below. Some of these metrics are available only to Pages, some only to Apps, and some to Posts, but the naming of each should indicate this. We have grouped the metrics into different categories.

Breakdown metrics for page post and page views insights will only return non-zero values.

Also, several video-related metrics will only return accurate values if you are the page video post creator. If you reshare another page's video post and retrieve its insights, these metric will instead return a value of 0. Metrics that return 0 for resharers are denoted with "Returns 0 for reshared videos" in their description.

Naming Patterns for Metrics

  • The _unique suffix indicates that this metric shows the number of unique users who performed a specific action. Metrics generated with the _unique suffix are approximate and may not be 100% accurate.
  • The _login and _logout suffixes indicate whether someone was logged into or out of Facebook.
  • The _source suffix indicates that the metric will be broken down into a list of referral sources. External referrals are broken down by domain. Internal referrals are broken down by Facebook-specific features such as 'Profile', 'Search', 'Requests', 'Suggestions', 'Stream', etc. In these case the value returned will be an object containing a series of key-value pairs where the key is the source name and the value is the metric for that source.
  • Most metrics will update once every 24 hours. Some metrics, marked with an *, are refreshed several times during the day.

Page and Post Stories and "People talking about this"

Beginning August 1, 2018, Page and Post Story engagement metrics have been renamed from stories to activity and Page Post Consumptions engagement metrics have been renamed from post_consumption* to post_clicks*. Please see the table below and the Graph API Changelog for more information.

Metric Name Description Values for `period`
page_content_activity_by_action_type_unique

The number of people talking about your Page's stories, by Page story type.

day, week, days_28

page_content_activity_by_age_gender_unique

The number of People Talking About the Page by user age and gender.

day, week, days_28

page_content_activity_by_city_unique

The number of People Talking About the Page by user city.

day, week, days_28

page_content_activity_by_country_unique

The number of people, aggregated per country, that are talking about your Page. Only the 45 countries with the most people talking about your page are included.

day, week, days_28

page_content_activity_by_locale_unique

The number of People Talking About the Page by user language.

day, week, days_28

page_content_activity

The number of stories created about your Page (Stories).

day, week, days_28

page_content_activity_by_action_type

The number of stories about your Page's stories, by Page story type.

day, week, days_28

post_activity*

The number of stories generated about your Page post ('Stories').

lifetime

post_activity_unique*

The number of people who created a story about your Page post ('People Talking About This' / PTAT).

lifetime

post_activity_by_action_type*

The number of stories created about your Page post, by action type.

lifetime

post_activity_by_action_type_unique*

The number of people who created a story about your Page post, by action type.

lifetime

Metric Renaming

Old Metric NameNew Metric Name as of August 1, 2018
page_storiespage_content_activity
post_story_addspost_activity
post_story_adds_uniquepost_activity_unique
post_story_adds_by_action_typepost_activity_by_action_type
post_story_adds_by_action_type_uniquepost_activity_by_action_type_unique
page_storytellers*page_content_activity_unique
page_stories_by_story_typepage_content_activity_by_action_type
page_storytellers_by_story_typepage_content_activity_by_action_type_unique
page_storytellers_by_age_genderpage_content_activity_by_age_gender_unique
page_storytellers_by_citypage_content_activity_by_city_unique
page_storytellers_by_countrypage_content_activity_by_country_unique
page_storytellers_by_localepage_content_activity_by_locale_unique
post_stories*post_activity
post_storytellers*post_activity_unique
post_stories_by_action_type*post_activity_by_action_type
post_storytellers_by_action_typepost_activity_by_action_type_unique
post_consumptions*post_clicks
post_consumptions_uniquepost_clicks_unique
post_consumptions_by_type*post_clicks_by_type
post_consumptions_by_type_uniquepost_clicks_by_type_unique

Page Impressions

Note that the unique impression insights values are calculated independently. Total page reach may not always be exactly equal to the sum of viral_unique and organic_unique.

Metric Name Description Values for `period`
page_impressions*

The number of times any content from your Page or about your Page entered a person's screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more.

day, week, days_28

page_impressions_unique*

The number of people who had any content from your Page or about your Page enter their screen. This includes posts, check-ins, ads, social information from people who interact with your Page and more.

day, week, days_28

page_impressions_paid*

The number of times any content from your Page or about your Page entered a person's screen through paid distribution such as an ad.

day, week, days_28

page_impressions_paid_unique*

The number of people who had any content from your Page or about your Page enter their screen through paid distribution such as an ad.

day, week, days_28

page_impressions_organic*

The number of times any content from your Page or about your Page entered a person's screen through unpaid distribution. This includes posts, check-ins, social information from people who interact with your Page and more.

day, week, days_28

page_impressions_organic_unique*

The number of people who had any content from your Page or about your Page enter their screen through unpaid distribution. This includes posts, check-ins, social information from people who interact with your Page and more.

day, week, days_28

page_impressions_viral*

The number of times any content from your Page or about your Page entered a person's screen with social information attached. Social information displays when a person's friend interacted with you Page or post. This includes when someone's friend likes or follows your Page, engages with a post, shares a photo of your Page and checks into your Page.

day, week, days_28

page_impressions_viral_unique*

The number of people who had any content from your Page or about your Page enter their screen through with social information attached. As a form of organic distribution, social information displays when a person's friend interacted with you Page or post. This includes when someone's friend likes or follows your Page, engages with a post, shares a photo of your Page and checks into your Page.

day, week, days_28

page_impressions_nonviral*

The number of times any content from your Page entered a person's screen. This does not include content created about your Page with social information attached. Social information displays when a person's friend interacted with you Page or post. This includes when someone's friend likes or follows your Page, engages with a post, shares a photo of your Page and checks into your Page.

day, week, days_28

page_impressions_nonviral_unique*

The number of people who had any content from your Page enter their screen. This does not include content created about your Page with social information attached. As a form of organic distribution, social information displays when a person's friend interacted with you Page or post. This includes when someone's friend likes or follows your Page, engages with a post, shares a photo of your Page and checks into your Page.

day, week, days_28

page_impressions_by_story_type

Total impressions of stories published by a friend about your Page by story type. (See possible types)

day, week, days_28

page_impressions_by_story_type_unique

The number of people who saw stories published by a friend about your Page by story type. (See possible types)

day, week, days_28

page_impressions_by_city_unique

The number of people who have seen any content associated with your Page by city.

day, week, days_28

page_impressions_by_country_unique

The number of people who have seen any content associated with your Page by country.

day, week, days_28

page_impressions_by_locale_unique

The number of people who have seen any content associated with your Page by user selected language.

day, week, days_28

page_impressions_by_age_gender_unique

The number of people who saw any content by your Page or about your Page, grouped by age and gender.

day, week, days_28

page_impressions_frequency_distribution

The number of people your Page reached broken down by how many times people saw any content about your Page.

day, week, days_28

page_impressions_viral_frequency_distribution

The number of people your Page reached from a story published by a friend, broken down by how many times people saw stories about your Page.

day, week, days_28

Page Engagement

Metric Name Description Values for `period`
page_engaged_users

The number of people who engaged with your Page. Engagement includes any click.

day, week, days_28

page_post_engagements*

The number of times people have engaged with your posts through likes, comments and shares and more.

day, week, days_28

page_consumptions

The number of times people clicked on any of your content.

day, week, days_28

page_consumptions_unique

The number of people who clicked on any of your content.

day, week, days_28

page_consumptions_by_consumption_type

The number of times people clicked on any of your content, by type.

day, week, days_28

page_consumptions_by_consumption_type_unique

The number of people who clicked on any of your content, by type.

day, week, days_28

page_places_checkin_total

The number of times people checked into a place.

day, week, days_28

page_places_checkin_total_unique

The number of people who checked into a place.

day, week, days_28

page_places_checkin_mobile

The number of times people checked into a place using mobile phones.

day, week, days_28

page_places_checkin_mobile_unique

The number of people who checked into a place using mobile phones.

day, week, days_28

page_places_checkins_by_age_gender

gender and age of people who checked in at your Place.

day

page_places_checkins_by_locale

top locales of people who checked into your Place.

day

page_places_checkins_by_country

top countries of people who checked into your Place.

day

page_negative_feedback

The number of times people took a negative action (e.g., un-liked or hid a post).

day, week, days_28

page_negative_feedback_unique

The number of people who took a negative action (e.g., un-liked or hid a post).

day, week, days_28

page_negative_feedback_by_type

The number of times people took a negative action broken down by type. (See possible types)

day, week, days_28

page_negative_feedback_by_type_unique

The number of people who took a negative action broken down by type. (See possible types)

day, week, days_28

page_positive_feedback_by_type

The number of times people took a positive action broken down by type. (See possible types)

day, week, days_28

page_positive_feedback_by_type_unique

The number of people who took a positive action broken down by type. (See possible types)

day, week, days_28

page_fans_online

The number of your fans who saw any posts on Facebook on a given day, broken down by hour of day in PST/PDT.

day

page_fans_online_per_day

The number of your fans who saw any posts on Facebook on a given day.

day

page_fan_adds_by_paid_non_paid_unique

The number of new people who have liked your page broken down by paid and non-paid.

day

Page Reactions

Metric Name Description Values for `period`
page_actions_post_reactions_like_total

Daily total post "like" reactions of a page.

day

page_actions_post_reactions_love_total

Daily total post "love" reactions of a page.

day

page_actions_post_reactions_wow_total

Daily total post "wow" reactions of a page.

day

page_actions_post_reactions_haha_total

Daily total post "haha" reactions of a page.

day

page_actions_post_reactions_sorry_total

Daily total post "sorry" reactions of a page.

day

page_actions_post_reactions_anger_total

Daily total post "anger" reactions of a page.

day

page_actions_post_reactions_total

Daily total post reactions of a page by type.

day

Page CTA Clicks

Metric Name Description Values for `period`
page_total_actions

The number of clicks on your Page's contact info and call-to-action button.

day, week, days_28

page_cta_clicks_logged_in_total

Total number of clicks on the Page CTA button by people who are logged in to Facebook.

day, week, days_28

page_cta_clicks_logged_in_unique

Unique number of clicks on the Page CTA button by people who are logged in to Facebook.

day, week, days_28

page_cta_clicks_by_site_logged_in_unique

Number of people who are logged in to Facebook and clicked on the CTA button, broken down by www, mobile, api or other.

day, week, days_28

page_cta_clicks_by_age_gender_logged_in_unique

Number of people who are logged in to Facebook and clicked the Page CTA button, broken down by age and gender group.

day, week, days_28

page_cta_clicks_logged_in_by_country_unique

Number of people who are logged in to Facebook and clicked the Page CTA button, broken down by country.

day, week, days_28

page_cta_clicks_logged_in_by_city_unique

Number of people who are logged in to Facebook and clicked the Page CTA button, broken down by city.

day, week, days_28

page_call_phone_clicks_logged_in_unique

Number of people who logged in to Facebook and clicked the Call Now button.

day, week, days_28

page_call_phone_clicks_by_age_gender_logged_in_unique

Number of people who logged in to Facebook and clicked the Call Now button, broken down by age and gender group.

day, week, days_28

page_call_phone_clicks_logged_in_by_country_unique

Number of people who logged in to Facebook and clicked the Call Now button, broken down by countries.

day, week, days_28

page_call_phone_clicks_logged_in_by_city_unique

Number of people who logged in to Facebook and clicked the Call Now button, broken down by city.

day, week, days_28

page_call_phone_clicks_by_site_logged_in_unique

Number of people who logged in to Facebook and clicked the Call Now button, broken down by www, mobile, api

day, week, days_28

page_get_directions_clicks_logged_in_unique

Number of people who logged in to Facebook and clicked the Get Directions button.

day, week, days_28

page_get_directions_clicks_by_age_gender_logged_in_unique

Number of people who logged in to Facebook and clicked the Get Directions button, broken down by age and gender group.

day, week, days_28

page_get_directions_clicks_logged_in_by_country_unique

Number of people who logged in to Facebook and clicked the Get Directions button, broken down by country.

day, week, days_28

page_get_directions_clicks_logged_in_by_city_unique

Number of people who logged in to Facebook and clicked the Get Directions button, broken down by city.

day, week, days_28

page_get_directions_clicks_by_site_logged_in_unique

Number of people who logged in to Facebook and clicked the Get Directions button, broken down by www, mobile, api or other.

day, week, days_28

page_website_clicks_logged_in_unique

Number of people who logged in to Facebook and clicked the goto website CTA button.

day, week, days_28

page_website_clicks_by_age_gender_logged_in_unique

Number of people who logged in to Facebook and clicked the goto website CTA button, broken down by age and gender group.

day, week, days_28

page_website_clicks_logged_in_by_country_unique

Number of people who logged in to Facebook and clicked the goto website CTA button, broken down by country.

day, week, days_28

page_website_clicks_logged_in_by_city_unique

Number of people who logged in to Facebook and clicked the goto website CTA button, broken down by city.

day, week, days_28

page_website_clicks_by_site_logged_in_unique

Number of people who logged in to Facebook and clicked the Page CTA button, broken down by www, mobile, api and other.

day, week, days_28

Page User Demographics

Metric Name Description Values for `period`
page_fans

The total number of people who have liked your Page. A Page must have 100 or more fans for this metric to return data.

lifetime

page_fans_locale

Aggregated language data about the people who like your Page based on the default language setting selected when accessing Facebook.

lifetime

page_fans_city

Aggregated Facebook location data, sorted by city, about the people who like your Page.

lifetime

page_fans_country

The number of people, aggregated per country, that like your Page. Only the 45 countries with the most people that like your Page are included.

lifetime

page_fans_gender_age

Aggregated demographic data about the people who like your Page based on the age and gender information they provide in their user profiles.

lifetime

page_fan_adds

The number of new people who have liked your Page.

day

page_fan_adds_unique

The number of new people who have liked your Page.

day, week, days_28

page_fans_by_like_source

This is a breakdown of the number of Page likes from the most common places where people can like your Page. (See possible types)

day

page_fans_by_like_source_unique

The number of people who liked your Page, broken down by the most common places where people can like your Page. (See possible types)

day

page_fan_removes

Unlikes of your Page.

day

page_fan_removes_unique

Unlikes of your Page.

day

page_fans_by_unlike_source_unique

The number of people who unliked your Page, broken down by the most common ways people can unlike your Page.

day

Page Content

Most of the metrics below can be retrieved using post_stories_by_action_type, post_consumptions_by_type, and page_consumptions_by_consumption_type.

Metric Name Description Values for `period`
page_tab_views_login_top_unique

The number of users logged in to Facebook who saw tabs on your Page. (See possible types)

day, week

page_tab_views_login_top

The number of times users logged in to Facebook saw tabs on your Page. (See possible types)

day, week

page_tab_views_logout_top

The number of times users not logged in to Facebook saw tabs on your Page. (See possible types)

day

Page Views

Metric Name Description Values for `period`
page_views_total

The number of times a Page's profile has been viewed by logged in and logged out people.

day, week, days_28

page_views_logout

The number of times a Page's profile has been viewed by people not logged in to Facebook.

day

page_views_logged_in_total

The number of times a Page's profile has been viewed by people logged in to Facebook.

day, week, days_28

page_views_logged_in_unique

The number of people logged in to Facebook who have viewed the Page profile.

day, week, days_28

page_views_external_referrals

Top referrering external domains sending traffic to your Page.

day

page_views_by_profile_tab_total

The number of people who have viewed each Page profile tab.

day, week, days_28

page_views_by_profile_tab_logged_in_unique

The number of people logged in to Facebook who have viewed your Page's profile, broken down by each tab.

day, week, days_28

page_views_by_internal_referer_logged_in_unique

The number of people logged in to Facebook who have viewed your Page, broken down by the internal referer within Facebook.

day, week, days_28

page_views_by_site_logged_in_unique

The number of people logged in to Facebook who have viewed your Page profile, broken down by the type of device.

day, week, days_28

page_views_by_age_gender_logged_in_unique

The number of people logged in to Facebook who have viewed your Page profile, broken down by gender group.

day, week, days_28

page_views

Deprecated. Use `page_views_total` instead. Number of times any tabs (e.g. Timeline, photo) of page's profile has been visited.

day

page_views_unique

Deprecated. Use `page_views_login_unique` instead. Page Views from users logged in to Facebook.

day, week

page_views_login

Deprecated. Use `page_views_logged_in_total` instead. Number of times any tabs (e.g. Timeline, photo) of page's profile has been visited from users logged in to Facebook.

day, week

page_views_login_unique

Deprecated. Use `page_views_loggedin_unique. Page Views from users logged in to Facebook.

day, week

Page Video Views

Metric Name Description Values for `period`
page_video_views

The number of times your Page's videos played for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_views_paid

The number of times your Page's promoted videos played for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds. For each impression of a video, we'll count video views separately and exclude any time spent replaying the video.

day, week, days_28

page_video_views_organic

The number of times your Page's videos played for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds, by organic reach. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_views_by_paid_non_paid*

The number of times your Page's videos played for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds, broken down by total, paid, and non-paid. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_views_autoplayed

The number of times your Page's videos automatically played for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_views_click_to_play

The number of times your Page's videos played for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds, after people clicked play. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_views_unique

The number of people who viewed your Page's videos for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_repeat_views

The number of times your Page's videos were replayed for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds.

day, week, days_28

page_video_complete_views_30s

The number of times your Page's videos played for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_complete_views_30s_paid

The number of times your Page's promoted videos played for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds. For each impression of a video, we'll count video views separately and exclude any time spent replaying the video.

day, week, days_28

page_video_complete_views_30s_organic

The number of times your Page's videos played for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds, by organic reach. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_complete_views_30s_autoplayed

The number of times your Page's automatically played videos played for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_complete_views_30s_click_to_play

The number of times your Page's videos played for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds, after people clicked play. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_complete_views_30s_unique

The number of people who viewed your Page's videos for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_complete_views_30s_repeat_views

The number of times your Page's videos replayed for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds.

day, week, days_28

post_video_complete_views_30s_autoplayed

The number of times your videos automatically played for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video. Returns 0 for reshared videos.

lifetime

post_video_complete_views_30s_clicked_to_play

The number of times your videos played for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds, after people clicked play. During a single instance of a video playing, we'll exclude any time spent replaying the video. Returns 0 for reshared videos.

lifetime

post_video_complete_views_30s_organic

The number of times your videos played for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds, by organic reach. During a single instance of a video playing, we'll exclude any time spent replaying the video. Returns 0 for reshared videos.

lifetime

post_video_complete_views_30s_paid

The number of times your promoted videos played for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds. For each impression of a video, we'll count video views separately and exclude any time spent replaying the video. Returns 0 for reshared videos.

lifetime

post_video_complete_views_30s_unique

The number of people who viewed your videos for at least 30 seconds, or for nearly their total length if they're shorter than 30 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

lifetime

page_video_views_10s

The number of times your Page's videos played for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_views_10s_paid

The number of times your Page's promoted videos played for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds. For each impression of a video, we'll count video views separately and exclude any time spent replaying the video.

day, week, days_28

page_video_views_10s_organic

The number of times your Page's videos played for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds, by organic reach. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_views_10s_autoplayed

The number of times your Page's videos automatically played for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_views_10s_click_to_play

The number of times your Page's videos played for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds, after people clicked play. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_views_10s_unique

The number of people who viewed your Page's videos for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, week, days_28

page_video_views_10s_repeat

The number of times your Page's videos replayed for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds.

day, week, days_28

page_video_view_time

The total time, in milliseconds, people viewed your Page's video.

day

Page Posts

Metric Name Description Values for `period`
page_posts_impressions*

The number of times your Page's posts entered a person's screen. Posts include statuses, photos, links, videos and more.

day, week, days_28

page_posts_impressions_unique*

The number of people who had any of your Page's posts enter their screen. Posts include statuses, photos, links, videos and more.

day, week, days_28

page_posts_impressions_paid*

The number of times your Page's posts entered a person's screen through paid distribution such as an ad.

day, week, days_28

page_posts_impressions_paid_unique*

The number of people who had any of your Page's posts enter their screen through paid distribution such as an ad.

day, week, days_28

page_posts_impressions_organic*

The number of times your Page's posts entered a person's screen through unpaid distribution.

day, week, days_28

page_posts_impressions_organic_unique*

The number of people who had any of your Page's posts enter their screen through unpaid distribution.

day, week, days_28

page_posts_served_impressions_organic_unique

The number of people who were served your Page's posts in their News Feed whether it entered their screen or not. Posts include statuses, photos, links, videos and more.

day, week, days_28

page_posts_impressions_viral*

The number of times your Page's posts entered a person's screen with social information attached. Social information displays when a person's friend interacted with you Page or post. This includes when someone's friend likes or follows your Page, engages with a post, shares a photo of your Page and checks into your Page.

day, week, days_28

page_posts_impressions_viral_unique*

The number of people who had any of your Page's posts enter their screen with social information attached. As a form of organic distribution, social information displays when a person's friend interacted with you Page or post. This includes when someone's friend likes or follows your Page, engages with a post, shares a photo of your Page and checks into your Page.

day, week, days_28

page_posts_impressions_nonviral*

The number of times your Page's posts entered a person's screen. This does not include content created about your Page with social information attached. Social information displays when a person's friend interacted with you Page or post. This includes when someone's friend likes or follows your Page, engages with a post, shares a photo of your Page and checks into your Page.

day, week, days_28

page_posts_impressions_nonviral_unique*

The number of people who had any posts by your Page enter their screen. This does not include content created about your Page with social information attached. As a form of organic distribution, social information displays when a person's friend interacted with you Page or post. This includes when someone's friend likes or follows your Page, engages with a post, shares a photo of your Page and checks into your Page.

day, week, days_28

page_posts_impressions_frequency_distribution

The number of people who saw your Page posts, broken down by how many times people saw your posts.

day, week, days_28

Page Post Impressions

Note that the unique impression insights values are calculated independently. Total page reach may not always be exactly equal to the sum of paid and non-paid unique values.

Metric Name Description Values for `period`
post_impressions*

The number of times your Page's post entered a person's screen. Posts include statuses, photos, links, videos and more.

lifetime

post_impressions_unique*

The number of people who had your Page's post enter their screen. Posts include statuses, photos, links, videos and more.

lifetime

post_impressions_paid*

The number of times your Page's post entered a person's screen through paid distribution such as an ad.

lifetime

post_impressions_paid_unique*

The number of people who had your Page's post enter their screen through paid distribution such as an ad.

lifetime

post_impressions_fan*

The number of impressions for your Page post by people who have liked your Page.

lifetime

post_impressions_fan_unique*

The number of people who have like your Page who saw your Page post.

lifetime

post_impressions_fan_paid*

The number of impressions for your Page post by people who like your Page in an Ad or Sponsored Story.

lifetime

post_impressions_fan_paid_unique*

The number of people who have like your Page and saw your Page post in an Ad or Sponsored Story.

lifetime

post_impressions_organic*

The number of times your Page's posts entered a person's screen through unpaid distribution.

lifetime

post_impressions_organic_unique*

The number of people who had your Page's post enter their screen through unpaid distribution.

lifetime

post_impressions_viral*

The number of times your Page's post entered a person's screen with social information attached. Social information displays when a person's friend interacted with you Page or post. This includes when someone's friend likes or follows your Page, engages with a post, shares a photo of your Page and checks into your Page.

lifetime

post_impressions_viral_unique*

The number of people who had your Page's post enter their screen with social information attached. As a form of organic distribution, social information displays when a person's friend interacted with you Page or post. This includes when someone's friend likes or follows your Page, engages with a post, shares a photo of your Page and checks into your Page.

lifetime

post_impressions_nonviral*

The number of times your Page's post entered a person's screen. This does not include content created about your Page with social information attached. Social information displays when a person's friend interacted with you Page or post. This includes when someone's friend likes or follows your Page, engages with a post, shares a photo of your Page and checks into your Page.

lifetime

post_impressions_nonviral_unique*

The number of people who had your Page's post enter their screen. This does not include content created about your Page with social information attached. As a form of organic distribution, social information displays when a person's friend interacted with you Page or post. This includes when someone's friend likes or follows your Page, engages with a post, shares a photo of your Page and checks into your Page.

lifetime

post_impressions_by_story_type*

The number of times this post was seen via a story published by a friend of the person viewing the post.

lifetime

post_impressions_by_story_type_unique*

The number of people who saw your Page post in a story from a friend, by story type.

lifetime

Page Post Engagement

Metric Name Description Values for `period`
post_engaged_users*

The number of people who clicked anywhere in your posts.

lifetime

post_negative_feedback*

The number of times people took a negative action in your post (e.g. hid it).

lifetime

post_negative_feedback_unique*

The number of people who took a negative action in your post (e.g., hid it).

lifetime

post_negative_feedback_by_type*

The number of times people took a negative action in your post broken down by type.

lifetime

post_negative_feedback_by_type_unique*

The number of people who took a negative action in your post broken down by type.

lifetime

post_engaged_fan

People who have liked your Page and engaged with your post.

lifetime

post_clicks*

The number of times people clicked on anywhere in your posts without generating a story.

lifetime

post_clicks_unique*

The number of people who clicked anywhere in your post without generating a story.

lifetime

post_clicks_by_type*

The number of times people clicked on anywhere in your posts without generating a story, by consumption type.

lifetime

post_clicks_by_type_unique*

The number of people who clicked anywhere in your post without generating a story, by consumption type.

lifetime

Page Post Reactions

Metric Name Description Values for `period`
post_reactions_like_total

Total "like" reactions of a post.

lifetime

post_reactions_love_total

Total "love" reactions of a post.

lifetime

post_reactions_wow_total

Total "wow" reactions of a post.

lifetime

post_reactions_haha_total

Total "haha" reactions of a post.

lifetime

post_reactions_sorry_total

Total "sorry" reactions of a post.

lifetime

post_reactions_anger_total

Total "anger" reactions of a post.

lifetime

post_reactions_by_type_total

Total post reactions by type.

lifetime

Page Video Posts

Metric Name Description Values for `period`
post_video_avg_time_watched

The average time, in milliseconds, people viewed your videos. Only available for videos created after August 25th 2016. Returns 0 for reshared videos.

lifetime

post_video_complete_views_organic

The number of times your videos played from the beginning to 95%, or more, of its length, by organic reach. During a single instance of a video playing, we'll exclude any time spent replaying the video. Returns 0 for reshared videos.

lifetime

post_video_complete_views_organic_unique

The number of people who viewed your videos from the beginning to 95%, or more, of its length, by organic reach. During a single instance of a video playing, we'll exclude any time spent replaying the video. Returns 0 for reshared videos.

lifetime

post_video_complete_views_paid

The number of times your promoted videos played from the beginning to 95%, or more, of its length. For each impression of a video, we'll count video views separately and exclude any time spent replaying the video. Returns 0 for reshared videos.

lifetime

post_video_complete_views_paid_unique

The number of people who viewed your promoted videos from the beginning to 95%, or more, of its length. For each impression of a video, we'll count video views separately and exclude any time spent replaying the video.

lifetime

post_video_retention_graph*

The number of times your videos played at each interval as a percentage of all views. Videos are divided into 40 equal intervals. This metric does not count impressions while the video was live. Retention graphs may show more impressions later in the video than at the beginning. People might start the video in the middle, skip ahead, save, and rewatch it from that point, or other similar behaviors.

lifetime

post_video_retention_graph_clicked_to_play

The number of times your videos played at each interval as a percentage of all views, after people clicked play. Videos are divided into 40 equal intervals. This metric does not count impressions while the video was live. Retention graphs may show more impressions later in the video than at the beginning. People might start the video in the middle, skip ahead, save, and rewatch it from that point, or other similar behaviors.

lifetime

post_video_retention_graph_autoplayed

The number of times your videos automatically played at each interval as a percentage of all automatic views. Videos are divided into 40 equal intervals.This metric does not count impressions while the video was live. Retention graphs may show more impressions later in the video than at the beginning. People might start the video in the middle, skip ahead, save, and rewatch it from that point, or other similar behaviors.

lifetime

post_video_views_organic

The number of times your videos played for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds, by organic reach. During a single instance of a video playing, we'll exclude any time spent replaying the video.

lifetime

post_video_views_organic_unique

The number of people who viewed your videos for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds, by organic reach. During a single instance of a video playing, we'll exclude any time spent replaying the video.

lifetime

post_video_views_paid

The number of times your promoted videos played for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds. For each impression of a video, we'll count video views separately and exclude any time spent replaying the video.

day, lifetime

post_video_views_paid_unique

The number of people who viewed your promoted videos for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds. For each impression of a video, we'll count video views separately and exclude any time spent replaying the video.

lifetime

post_video_length

The length, in milliseconds, of a video post.

lifetime

post_video_views

The number of times your videos played for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

day, lifetime

post_video_views_unique

The number of people who viewed your videos for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

lifetime

post_video_views_autoplayed

The number of times your videos automatically played for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

lifetime

post_video_views_clicked_to_play

The number of times your videos played for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds, after people clicked play. During a single instance of a video playing, we'll exclude any time spent replaying the video.

lifetime

post_video_views_10s

The number of times your videos played for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

lifetime

post_video_views_10s_unique

The number of people who viewed your videos for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds. For each impression of a video, we'll count video views separately and exclude any time spent replaying the video.

lifetime

post_video_views_10s_autoplayed

The number of times your videos played automatically for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

lifetime

post_video_views_10s_clicked_to_play

The number of times your videos played for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds, after people clicked play. During a single instance of a video playing, we'll exclude any time spent replaying the video.

lifetime

post_video_views_10s_organic

The number of times your videos played for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds, by organic reach. During a single instance of a video playing, we'll exclude any time spent replaying the video.

lifetime

post_video_views_10s_paid

The number of times your promoted videos played for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds. For each impression of a video, we'll count video views separately and exclude any time spent replaying the video.

day, lifetime

post_video_views_10s_sound_on

The number of times your videos played with sound on for at least 10 seconds, or for nearly their total length if they're shorter than 10 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

lifetime

post_video_views_sound_on

The number of times your videos played with sound on for at least 3 seconds, or for nearly their total length if they're shorter than 3 seconds. During a single instance of a video playing, we'll exclude any time spent replaying the video.

lifetime

post_video_view_time

The total time, in milliseconds, your videos played, including videos played for less than 3 seconds and replays. Returns 0 for reshared videos.

day, lifetime

post_video_view_time_organic

The total time, in milliseconds, your videos played by organic reach. Returns 0 for reshared videos.

day, lifetime

post_video_view_time_by_age_bucket_and_gender

The total time, in milliseconds, your videos played for your Top Audiences, age and gender.

lifetime

post_video_view_time_by_region_id

The total time, in milliseconds, your videos played for your Top 45 Locations, Region - Country.

lifetime

post_video_views_by_distribution_type

The number of times your videos played by distribution type; page_owned and shared.

lifetime

post_video_view_time_by_distribution_type

The total time, in milliseconds, your videos played by distribution type; page_owned and shared.

lifetime

post_video_view_time_by_country_id

The total number of minutes your videos played for your Top 45 Locations; Country.

lifetime

Video Ad Breaks

Data is available for dates after October 15, 2017.

Metric Name Description Values for period

page_daily_video_ad_break_ad_ impressions_by_crosspost_status

The total number of times an ad was shown during ad breaks in crossposted videos.

day

page_daily_video_ad_ break_cpm_by_crosspost_status

The average amount paid by advertisers for 1,000 of impressions of their ads in a crossposted videos. This is a gross number and includes the amount paid to Facebook.

day

page_daily_video_ad_ break_earnings_by_crosspost_status

An estimate of the amount you earned from ad breaks in a crossposted videos, based on the number of impressions and CPM of ads shown. Actual payments may differ if there are content ownership claims or other adjustments.

day

post_video_ad_break_ad_impressions

The total number of times an ad was shown during ad breaks in your videos.

day, lifetime

post_video_ad_break_earnings

An estimate of the amount you earned from ad breaks in your videos, based on the number of impressions and CPM of ads shown. Actual payments may differ if there are content ownership claims or other adjustments.

day, lifetime

post_video_ad_break_ad_cpm

The average amount paid by advertisers for 1,000 impressions of their ads in your videos. This number also includes the amount paid to Facebook.

day, lifetime

Special Values

Page Like Sources

For metrics:

  • page_fans_by_like_source
  • page_fans_by_like_source_unique
Name Description
Ads

Page likes that came from people who saw your Page or post in an ad.

News Feed

Page likes that came from people who saw content posted by your Page or about your Page in News Feed.

Page Suggestions

Page likes that came from people saw your Page in a list of suggested Pages.

Restored Likes from Reactivated Accounts

Page likes that came from people who reactivated their Facebook profile.

Search

Page likes that came from people who saw you Page or post in search.

Your Page

Page likes that came from people who visited your Page.

Page Unlike Sources

For metrics:

  • page_fans_by_unlike_source_unique
  • page_fans_by_unlike_source

Negative Feedback Types

For metrics:

  • page_negative_feedback_by_type
Name Description
hide_clicks

Hide this story

hide_all_clicks

Hide all posts from this page

report_spam_clicks

Report an object as a spam

unlike_page_clicks

Unlike a page

xbutton_clicks

Deprecated. This is no longer logged

Positive Feedback Types

For metrics:

  • page_positive_feedback_by_type
Name Description
like

Like a story

comment

Comment on a story

link

Share a story

answer

Answer a question

claim

Claim an offer

rsvp

Respond to an event

Page Story Types

Name Description
checkin

Page checkins

coupon

Offer claims

event

RSVPing to event

fan

Page likes

mention

Page mentions

page post

Posts by a Page

question

Question answers

user post

Posts by people on a Page

other

Other types

Tab Types

Name Description
allactivity

Administrative tab

app

Custom created tab

info

About tab view

insights

Insights tab

likes

Likes tab

locations

Map tab

photos

Photos tab

photos_albums

Photos tab

photos_stream

Photos tab

profile

Pages timeline

profile_info

Info tab

profile_likes

Likes tab

profile_photos

Photos tab

timeline

Pages timeline

events

Events tab

videos

Videos tab

wall

Timeline