Graph API Version

Insights Metric /{object-id}/insights/{metric-name}

Facebook Insights is a product available to all Pages and Apps on Facebook, and any domains claimed by a site developer 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 30 people that like it.

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

*Note:

  • 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.

Reading

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

Graph API Explorer
GET /v2.7/{object-id}/insights/{metric-name} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{object-id}/insights/{metric-name}'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{object-id}/insights/{metric-name}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{object-id}/insights/{metric-name}",
    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-name}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • Any valid access token can be used for publicly available metrics (currently page_fans_country or page_storytellers_by_country).
  • A user access token with read_insights permission can retrieve metrics for all pages and domains owned by this user.
  • A page access token with read_insights permission can retrieve all metrics for that Page.

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.

Fields

NameDescriptionType

description

The full description of the metric.

string

id

ID of the insight.

string

name

Name of the metric.

string

period

Length of the period during which the insights were collected.

string

values

Individual data points for the insight grouped by different time periods (determined by period).

object[]

value

The value of the metric in a period. The content of this field varies based on the metric type being requested.

various

end_time

The end time of the period that this metric value refers to.

datetime

Modifiers

NameDescriptionType

period

Change the period (from now) over which the metric has been collected. Valid values for each metric are listed below.

enum{day, week, month, lifetime}

breakdown

Usuable only with the application_mobile_app_installs metric to show a breakdown of installs by a specific grouping.

enum{gender_age, country, locale}

GET /v2.7/{object-id}/insights/{metric-name}?period=month HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{object-id}/insights/{metric-name}',
  array (
    'period' => 'month',
  )
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{object-id}/insights/{metric-name}",
    {
        "period": "month"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("period", "month");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{object-id}/insights/{metric-name}",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"period": @"month",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{object-id}/insights/{metric-name}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

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.

Naming Patterns for Metrics

  • The _unique suffix indicates that this metric shows the number of unique users who performed a specific action.
  • 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.
  • Metrics that are marked with * are available in real-time, i.e., they are refreshed approximately every 15 minutes. Most other metrics will update once every 24 hours.

Page and Post Stories and "People talking about this"

NameDescriptionValues for `period`

page_stories

The number of stories created about your Page (Stories)

day, week, days_28

page_storytellers*

The number of people sharing stories about your page ('People Talking About This' / PTAT). These stories include liking your Page, posting to your Page's Wall, liking, commenting on or sharing one of your Page posts, answering a Question you posted, RSVPing to one of your events, mentioning your Page, phototagging your Page or checking in at your Place

Note that currently only the weekly value is in real-time if you set until=now in the request. This metric is deprecated after the deprecate_PTAT migration.

day, week, days_28

page_stories_by_story_type

The number of stories about your Page's stories, by Page story type (see Page story types)

day, week, days_28

page_storytellers_by_story_type

The number of people talking about your Page's stories, by Page story type (see Page story types)

day, week, days_28

page_storytellers_by_age_gender

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

day, week, days_28

page_storytellers_by_city

The number of People Talking About the Page by user city

day, week, days_28

page_storytellers_by_country

The number of People Talking About the Page by user country

day, week, days_28

page_storytellers_by_locale

The number of People Talking About the Page by user language

day, week, days_28

post_stories*

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

lifetime

post_storytellers*

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

lifetime

post_stories_by_action_type*

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

lifetime

post_storytellers_by_action_type*

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

lifetime

post_story_adds

The number of stories generated about your Page post.

lifetime

post_story_adds_unique

The number of unique people who created a story by interacting with your Page post.

lifetime

post_story_adds_by_action_type

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

lifetime

post_story_adds_by_action_type_unique

The number of unique people who created a story about your Page post by interacting with it.

lifetime

Page Impressions

Note that total page reach may be less than the sum of organic and viral reach. This is because some of the same users can be both present in viral_unique and organic_unique but are only counted once in page_impressions_unique.

NameDescriptionValues for `period`

page_impressions

The total number of impressions seen of any content associated with your Page

day, week, days_28

page_impressions_unique

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

day, week, days_28

page_impressions_paid

The number of impressions of a Sponsored Story or Ad pointing to your Page

day, week, days_28

page_impressions_paid_unique

Number of people who saw a sponsored story or Ad about your Page

day, week, days_28

page_impressions_organic

The number of times your posts were seen in News Feed or Ticker or on visits to your Page. These impressions can be Fans or non-Fans

day, week, days_28

page_impressions_organic_unique

The number of people who visited your Page, or saw your Page or one of its posts in News Feed or Ticker. These impressions can be Fans or non-Fans

day, week, days_28

page_impressions_viral

The number of impressions of a story published by a friend about your Page. These stories include liking your Page, posting to your Page's Wall, liking, commenting on or sharing one of your Page posts, answering a Question you posted, RSVPing to one of your events, mentioning your Page, phototagging your Page or checking in at your Place (see Page story types)

day, week, days_28

page_impressions_viral_unique

The number of people who saw your Page or one of its posts from a story published by a friend. These stories include liking your Page, posting to your Page's Wall, liking, commenting on or sharing one of your Page posts, answering a Question you posted, RSVPing to one of your events, mentioning your Page, phototagging your Page or checking in at your Place (see Page story types)

day, week, days_28

page_impressions_by_story_type

Total impressions of stories published by a friend about your Page by story type (see Page story 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 Page story 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 have seen any content associated with your Page by age and gender grouping

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_impressions_by_paid_non_paid

The total number of impressions seen of any content associated with your Page, broken down by total, paid, and non-paid

day, week, days_28

page_impressions_by_paid_non_paid_unique

The number of people seen of any content associated with your Page, broken down by total, paid, and non-paid

day, week, days_28

Page Engagement

NameDescriptionValues for `period`

page_engaged_users

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

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 negative feedback 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 negative feedback types)

day, week, days_28

page_positive_feedback_by_type

The number of times people took a positive action broken down by type (see positive feedback 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 positive feedback 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

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.

Daily

Page Reactions

NameDescriptionValues for `period`

page_actions_post_reactions_like_total

Daily total post "like" reactions of a page

daily

page_actions_post_reactions_love_total

Daily total post "love" reactions of a page

daily

page_actions_post_reactions_wow_total

Daily total post "wow" reactions of a page

daily

page_actions_post_reactions_haha_total

Daily total post "haha" reactions of a page

daily

page_actions_post_reactions_sorry_total

Daily total post "sorry" reactions of a page

daily

page_actions_post_reactions_anger_total

Daily total post "anger" reactions of a page

daily

page_actions_post_reactions_total

Daily total post reactions of a page by type

daily

Page CTA Clicks

NameDescriptionValues for `period`

page_cta_clicks_logged_in_total

Total number of clicks on the Page CTA button by people who are logged into 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 into Facebook

day, week, days_28

page_cta_clicks_by_site_logged_in_unique

Number of unique people who are logged into 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 unique people who are logged into Facebook and clicked the Page CTA button, broken down by age and gender group

day, week, days_28

Page User Demographics

NameDescriptionValues for `period`

page_fans

The total number of people who have liked your Page.

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

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

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

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 like sources).

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 like sources).

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 below metrics can be retrieved using post_stories_by_action_type, post_consumptions_by_type, and page_consumptions_by_consumption_type.

NameDescriptionValues for `period`

page_tab_views_login_top_unique

The number of users logged into Facebook who saw tabs on your Page (see Tab Types)

day, week

page_tab_views_login_top

The number of times users logged into Facebook saw tabs on your Page (see Tab Types)

day, week

page_tab_views_logout_top

The number of times users not logged into Facebook saw tabs on your Page

day

Page Views

NameDescriptionValues 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 into Facebook

day

page_views_logged_in_total

The number of times a Page’s profile has been viewed by people logged into Facebook

day, week, days_28

page_views_logged_in_unique

The number of people logged into 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 into 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 into 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 into 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 into 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 into 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 into Facebook

day, week

page_views_login_unique

Deprecated. Use `page_views_loggedin_unique. Page Views from users logged into Facebook

day, week

Page Video Views

NameDescriptionValues for `period`

page_video_views

Total number of times page's videos have been viewed for more than 3 seconds

day, week, days_28

page_video_views_paid

Total number of times page's promoted videos have been viewed for more than 3 seconds

day, week, days_28

page_video_views_organic

Total number of times page's videos have been viewed for more than 3 seconds by organic reach

day, week, days_28

page_video_views_autoplayed

Total number of times page's autoplayed videos have been viewed for more than 3 seconds

day, week, days_28

page_video_views_click_to_play

Total number of times page's videos have been viewed after the user clicks on play for more than 3 seconds

day, week, days_28

page_video_views_unique

Total number of times page's videos have been played for unique people for more than 3 seconds

day, week, days_28

page_video_repeat_views

Total number of times that people replay a page's videos for more than 3 seconds

day, week, days_28

page_video_complete_views_30s

Total number of times page's videos have been viewed for more than 30 seconds

day, week, days_28

page_video_complete_views_30s_paid

Total number of times page's promoted videos have been viewed to the end, or for more than 30 seconds

day, week, days_28

page_video_complete_views_30s_organic

Total number of times page's videos have been viewed to the end, or viewed for more than 30 seconds by organic reach

day, week, days_28

page_video_complete_views_30s_autoplayed

Total number of times page's autoplayed videos have been viewed to the end, or viewed for more than 30 seconds

day, week, days_28

page_video_complete_views_30s_click_to_play

Total number of times page's videos have been viewed to the end, or viewed after the user clicks on play for more than 30 seconds

day, week, days_28

page_video_complete_views_30s_unique

Total number of times page's videos have been played for unique people to the end, or viewed for more than 30 seconds

day, week, days_28

page_video_complete_views_30s_repeat_views

Total number of times that people replay a page's videos to the end, or for more than 30 seconds

day, week, days_28

post_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.

day, week, days_28

post_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.

day, week, days_28

post_video_complete_views_30s_organic

Number of times your video was viewed for 30 seconds or viewed to the end, whichever came first, without a paid promotion.

day, week, days_28

post_video_complete_views_30s_paid

Number of times your video was viewed for 30 seconds or viewed to the end, whichever came first, after a paid promotion.

day, week, days_28

post_video_complete_views_30s_unique

Total number of times page's videos have been viewed for more than 30 seconds by unique users.

day, week, days_28

Page Posts

NameDescriptionValues for `period`

page_posts_impressions

The number of impressions that came from all of your posts

day, week, days_28

page_posts_impressions_unique

The number of people who saw any of your Page posts

day, week, days_28

page_posts_impressions_paid

The number of impressions of your Page posts in an Ad or Sponsored Story

day, week, days_28

page_posts_impressions_paid_unique

The number of people who saw your Page posts in an Ad or Sponsored Story

day, week, days_28

page_posts_impressions_organic

The number of impressions of your posts in News Feed or Ticker or on your Page

day, week, days_28

page_posts_impressions_organic_unique

The number of people who saw your Page posts in News Feed or Ticker, or on your Page's Wall

day, week, days_28

page_posts_impressions_viral

The number of times users saw your posts via stories published by their friends

day, week, days_28

page_posts_impressions_viral_unique

The number of people who saw your Page posts via a story from a friend

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_posts_impressions_by_paid_non_paid

The number of impressions that came from all of your posts, broken down by total, paid, and non-paid

day, week, days_28

page_posts_impressions_by_paid_non_paid_unique

The number of people who saw any of your Page posts, broken down by total, paid, and non-paid

day, week, days_28

post_interests_impressions

The number of matched audience targeting impressions of your Page post on News Feed.

lifetime

post_interests_impressions_unique

The total number of people matched the audience targeting on Page post on News Feed was served.

lifetime

post_interests_consumptions_unique

The number of people who matched the audience targeting that clicked anywhere in your post on News Feed.

lifetime

post_interests_consumptions

The number of clicks anywhere in your post on News Feed from the user that matched the audience targeting on it.

lifetime

post_interests_consumptions_by_type_unique

The number of people who matched the audience targeting on post that clicked anywhere in your post on News Feed, by type.

lifetime

post_interests_consumptions_by_type

The number of clicks anywhere in your post on News Feed from users that matched the audience targeting on the post, by type.

lifetime

post_interests_action_by_type_unique

The number of unique people matched the audience targeting on the post on News Feed from who created a story about your Page post by interacting with it.

lifetime

post_interests_action_by_type

The number of stories created about your Page post on News Feed, from users that matched the Audience Targeting on the Post by action type.

lifetime

Page Post Impressions

NameDescriptionValues for `period`

post_impressions*

The number of impressions for your Page post

lifetime

post_impressions_unique*

The number of people who saw your Page post

lifetime

post_impressions_paid*

The number of impressions for your Page post in an Ad or Sponsored Story

lifetime

post_impressions_paid_unique*

The number of people who saw your Page post in an Ad or Sponsored Story

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 impressions of your post in Newsfeed, Ticker, or on your Page's Wall

lifetime

post_impressions_organic_unique*

The number of people who saw your post in their Newsfeed or Ticker or on your Page's Wall

lifetime

post_impressions_viral*

The number of impressions of your Page post in a story generated by a friend

lifetime

post_impressions_viral_unique*

The number of people who saw your page post in a story from a friend

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

post_impressions_by_paid_non_paid*

The number of impressions for your Page post, broken down by total, paid, and non-paid

lifetime

post_impressions_by_paid_non_paid_unique*

The number of people who saw your Page post, broken down by total, paid, and non-paid

lifetime

Page Post Engagement

NameDescriptionValues for `period`

post_consumptions*

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

lifetime

post_consumptions_unique*

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

lifetime

post_consumptions_by_type*

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

lifetime

post_consumptions_by_type_unique*

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

lifetime

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_fan_reach

Post reach by people who like your page.

lifetime

page_story_adds

The number of stories created about your Page.

Daily

page_story_adds_by_age_gender_unique

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

Daily

page_story_adds_by_city_unique

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

Daily

page_story_adds_by_country_unique

The number of People Talking About the Page by user country

Daily

Page Video Posts

NameDescriptionValues for `period`

post_video_avg_time_watched

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

lifetime

post_video_complete_views_organic

The number of times your video was organically viewed from the beginning to 95% of its length

lifetime

post_video_complete_views_organic_unique

The number of people who viewed your video organically from the beginning to 95% of its length

lifetime

post_video_complete_views_paid

The number of times your video was viewed via paid impression from the beginning to 95% of its length

lifetime

post_video_complete_views_paid_unique

The number of people who viewed your video via paid impression from the beginning to 95% of its length

lifetime

post_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

post_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

post_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

post_video_views_organic

The number of times your video was organically viewed for 3 seconds or more

lifetime

post_video_views_organic_unique

The number of people who viewed at least 3 seconds of your video organically

lifetime

post_video_views_paid

The number of times your video was viewed via paid impression for 3 seconds or more

lifetime, day

post_video_views_paid_unique

The number of people who viewed at least 3 seconds of your video via paid impression

lifetime

post_video_length

Length of a video post (in milliseconds)

lifetime

post_video_views

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

lifetime, day

post_video_views_unique

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

lifetime

post_video_views_autoplayed

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

lifetime

post_video_views_clicked_to_play

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

lifetime

post_video_views_10s_unique

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

lifetime

post_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

post_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

post_video_views_10s_organic

Number of times your video was viewed for 10 seconds or viewed to the end (whichever happened first) without paid promotion.

lifetime

post_video_views_10s_paid

Number of times your video was viewed for 10 seconds or viewed to the end (whichever happened first) with paid promotion

lifetime, day

post_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

post_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

post_video_view_time

Total time (in milliseconds) video has been viewed

lifetime, day

post_video_view_time_organic

Total time (in milliseconds) video has been viewed without paid promotion

lifetime, day

post_video_view_time_by_age_bucket_and_gender

Total time (in milliseconds) video has been viewed by Top Audiences.

lifetime

post_video_view_time_by_region_id

Total time (in milliseconds) video has been viewed by Top 45 Locations (Region - Country).

lifetime

post_video_views_by_distribution_type

Number of times your video was viewed by distribution type (page_owned and shared).

lifetime

post_video_view_time_by_distribution_type

Total time (in milliseconds) video has been viewed by distribution type (page_owned and shared).

lifetime

Domain Content

NameDescriptionValues for `period`

domain_feed_clicks

The number of clicks sent to your site from stories in News Feed, Page Walls, or Profile Walls

lifetime, day

domain_feed_views

The number of times people viewed stories that link to your site in News Feed, Page Walls, or Profile Walls

lifetime, day

domain_stories

The number of times people posted a link to your site through an action on a social plugin or through a status message or Wall post

lifetime, day

domain_widget_comments_adds

The number of times people left comments on your site using the Comments plugin.

lifetime, day

domain_widget_comments_views

Comments Box impressions on your domain

lifetime, day

domain_widget_comments_feed_views

The number of times people viewed stories generated from Comments Box comments on your site.

lifetime, day

domain_widget_comments_feed_clicks

The number of clicks sent to your site from Comment stories.

lifetime, day

domain_widget_like_views

The number of times people viewed Like buttons on your site

lifetime, day

domain_widget_likes

The number of times people clicked the Like button on your site

lifetime, day

domain_widget_like_feed_views

The number of times people viewed stories generated from Like button clicks on your site

lifetime, day

domain_widget_like_feed_clicks

The number of clicks sent to your site from stories in News Feed, Page Walls, or Profile Walls

lifetime, day

domain_widget_send_views

Impressions on the Send Button on your domain

lifetime, day

domain_widget_send_clicks

The number of times people sent messages from your domain using the Send button

lifetime, day

domain_widget_send_inbox_views

Views of Inbox messages generated by the Send Button

lifetime, day

domain_widget_send_inbox_clicks

The number of clicks sent to your site from Send button messages

lifetime, day

Special Values

Page Like Sources

For metrics:

  • page_fans_by_like_source
  • page_fans_by_like_source_unique
SourceDescription

page_suggestion

People who liked your Page through an invite from an admin

page_timeline

People who liked your Page from the Likes section of their own Timeline or someone else's

ads

People who clicked 'Like' in an Ad or Sponsored Story pointing to your Page on desktop

mobile_ads

People who clicked 'Like' in an Ad or Sponsored Story pointing to your Page on mobile

registration

People you added to your Page as admins

mobile

'People who liked your Page from a mobile device

wizard_suggestion

People who liked your Page in the New User Wizard when registering for Facebook

profile_connect

People who liked your Page on the Page itself or in a News Feed or ticker story

external_connect

People who liked your Page from an external site using a Facebook social plugin

recommended_pages

People who liked your Page from a Recommended Pages unit on the right column of Facebook

favorites

Other Pages that have liked your Page

api

People who liked your Page through an app developed by a third party

page_browser

People who liked your Page using Facebook's Page Browser

mobile_page_browser

People who liked your Page using Facebook's Page Browser on mobile

hovercard

People who liked your Page from the popup window they get when they hover over a link that leads to your Pag

search

People who liked your Page from their search results

page_profile

People who liked your Page on the Page itself

ticker

People who liked your Page from a story they saw about it in ticker

like_story

People who liked your Page from a story they saw about a friend liking it

feed_chaining

People who liked your Page after Facebook automatically suggested a story about a friend liking your page

all_category_pyml

People who liked your Page after seeing a PYML suggestion

page_suggestions_on_liking

People who liked your Page after seeing the Page in suggestions upon liking another Page on desktop

mobile_page_suggestions_on_liking

People who liked your Page after seeing the Page in suggestions upon liking another Page on mobile

fan_context_story

People who liked your Page after seeing a story of a friend interacting with the Page

sponsored_story

People who liked your Page after seeing a sponsored story

page_invite_escape_hatch_finch

People who liked your Page after being invited

page_admin_num_posts

Number of posts made by the admin of a Page.

page_admin_num_posts_by_type

Number of posts made by the admin of a Page broken down by post type.

Negative Feedback Types

For metrics:

  • page_negative_feedback_by_type
  • page_negative_feedback_by_type_unique
TypeDescription

hide_all

hide all stories from a Page

hide

hide this story

unlike_page

unlike a page

report_spam

report an object as a spam

Positive Feedback Types

For metrics:

  • page_positive_feedback_by_type
  • page_positive_feedback_by_type_unique
TypeDescription

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

TypeDescription

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

Tab Types

TypeDescription

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