Insights

An object containing statistics about applications, pages, and domains.

The Page, Application and Domain objects have an insights connection of this type. Post objects also have this connection where the Post was made by a Page.

Available metrics include application and page hits, adds, removes, and likes.

Use Facebook Insights to claim your domain.

Insights can be retrieved only as an array. To read Insights you need

• a generic access_token for the publicly available application_active_users metric
• a generic app access_token for all Insights for that app
• read_insights permissions for all apps, pages and domains owned by this user

Example

The application active users metric on the Graffiti app:

https://graph.facebook.com/2439131959/insights/application_active_users?since=1329724800&until=1329984000

Note: That start and end dates can be applied using since and until unix timestamps based on midnight in PST described in UTC.

---

Fields

The Insights object has the following fields.

Name	Description	Permissions	Returns
id	ID of the insight	generic access_token or read_insights	string
name	Name of the metric	generic access_token or read_insights	string
period	Length of the period during which the insights were collected	generic access_token or read_insights	string
values	Individual data points for the insight	generic access_token or read_insights	array of objects containing value and end_time
description	The full description of the metric	generic access_token or read_insights	string

Metrics

The following is a full list of Insights metrics to be used with the Insights Graph API object or the FQL Insights table.

• The _unique suffix indicates the number of unique users who performed a specific action - aka "Reach."
• The _login and _logout suffixes indicate page views by users logged in to Facebook and users not logged in to 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.
• Metrics that are marked with * are available in real-time, i.e., they are refreshed approximately every 15 minutes.

Application Users

Name	Description	Available Periods
application_active_users	1 day, 7 day, and 30 day counts of users who have engaged with your app or viewed your app	day, week, month
application_active_users_locale	Top locales of your active users	day
application_active_users_city	Top cities of your active users	day
application_active_users_country	Top countries of your active users	day
application_active_users_gender	Gender of your active users	day
application_active_users_age	Age of your active users	day
application_active_users_gender_age	Gender and age demographics of your active users	day
application_installed_users	Total installations of your app or connections to your Connect app	lifetime
application_installed_users_locale	Top locales of your app's installed user base	lifetime
application_installed_users_city	Top cities of your app's installed user base	lifetime
application_installed_users_country	Top countries of your app's installed user base	lifetime
application_installed_users_gender	Gender of your app's installed user base	lifetime
application_installed_users_age	Age of your app's installed user base	lifetime
application_installed_users_gender_age	Gender and age demographics of your app's installed user base	lifetime
application_installation_adds	New installations of your app or connections to your Connect site. Follows acceptance of your Terms of Service	day
application_installation_adds_unique	New installations of your app or connections to your Connect site. Follows acceptance of your Terms of Service	day
application_installation_removes	Removed installations of your app or connections to your Connect site	day
application_installation_removes_unique	Removed installations of your app or connections to your Connect site	day
application_tos_views	Impressions of the Terms Of Service dialog of your app	day
application_tos_views_unique	Impressions of the Terms Of Service dialog of your app	day
application_permission_views_top	Impressions of each permissions dialog type	day
application_permission_views_top_unique	Impressions of each permissions dialog type	day
application_permission_grants_top	Impressions of each permissions dialog type	day
application_permission_grants_top_unique	Impressions of each permissions dialog type	day
application_block_adds	Blocks of your app	day
application_block_adds_unique	Blocks of your app	day
application_block_removes	Removed blocks of your app	day
application_block_removes_unique	Removed blocks of your app	day

Application Mobile Users

This metric will return the total numbers of who have installed your app on mobile, but it can also be queried with an additional breakdown parameter that can be one of:

• gender_age
• country
• locale

Note: You must use an app access token to make this call.

Name	Description	Available Periods
application_mobile_app_installs*	Info about the number and demographics of users who installed your app.	day

Application Content

Name	Description	Available Periods
application_like_adds	Likes created via your app	day
application_like_adds_unique	Likes created via your app	day
application_like_removes	Likes deleted via your app	day
application_like_removes_unique	Likes deleted via your app	day
application_comment_adds	Comments created via your app	day
application_comment_adds_unique	Comments created via your app	day
application_photos	Photos created via your app	day
application_photos_unique	Photos created via your app	day
application_shares	Shares Created by your app via the Links.post method	day
application_shares_unique	Shares Created by your app via the Links.post method	day
application_status_updates	Status Updates created via your app	day
application_status_updates_unique	Status Updates created via your app	day
application_stream_stories	Stream.publish stories created via your app	day
application_stream_stories_unique	Stream.publish stories created via your app	day
application_feed_form_views	Impressions of the Feed form dialog	day
application_feed_form_views_unique	Impressions of the Feed form dialog from users logged into Facebook	day
application_feed_form_views_login	Impressions of the Feed form dialog from users logged into Facebook	day
application_feed_form_views_login_unique	Impressions of the Feed form dialog from users logged into Facebook	day
application_feed_form_views_logout	Impressions of the Feed form dialog from users not logged into Facebook	day

Plugins

Name	Description	Available Periods
application_widget_activity_views	Impressions of your activity plugin	day
application_widget_activity_views_unique	Activity Plugin impressions from users logged into Facebook	day
application_widget_activity_views_login	Activity Plugin impressions from users logged into Facebook	day
application_widget_activity_views_login_unique	Activity Plugin impressions from users logged into Facebook	day
application_widget_activity_views_logout	Activity Plugin impressions from users not logged into Facebook	day
application_widget_activity_views_external_referrals	Top domains of impressions of your Activity plugins	day
application_widget_comments_views	Impressions of your Comments plugin	day
application_widget_comments_views_unique	Impressions of your Comments plugin from users logged into Facebook	day
application_widget_comments_views_login	Impressions of your Comments plugin from users logged into Facebook	day
application_widget_comments_views_login_unique	Impressions of your Comments plugin from users logged into Facebook	day
application_widget_comments_views_logout	Impressions of your Comments plugin from users not logged into Facebook	day
application_widget_fan_views	Impressions of your Like Box	day
application_widget_fan_views_unique	Impressions of your Like Box plugin from users logged into Facebook	day
application_widget_fan_views_login	Impressions of your Like Box plugin from users logged into Facebook	day
application_widget_fan_views_login_unique	Impressions of your Like Box plugin from users logged into Facebook	day
application_widget_fan_views_logout	Impressions of your Like Box plugin from users not logged into Facebook	day
application_widget_fan_views_external_referrals	Top domains of impressions of your Like Box plugins	day
application_widget_like_views	Impressions of your Like plugin	day
application_widget_like_views_unique	Like Button impressions from users logged into Facebook	day
application_widget_like_views_login	Like Button impressions from users logged into Facebook	day
application_widget_like_views_login_unique	Like Button impressions from users logged into Facebook	day
application_widget_like_views_logout	Like Button impressions from users not logged into Facebook	day
application_widget_like_views_external_referrals	Top domains of impressions of your Like plugins	day
application_widget_live_stream_views	Impressions of your Live Stream plugin	day
application_widget_live_stream_views_unique	Impressions of your Live Stream plugin from users logged into Facebook	day
application_widget_live_stream_views_login	Impressions of your Live Stream plugin from users logged into Facebook	day
application_widget_live_stream_views_login_unique	Impressions of your Live Stream plugin from users logged into Facebook	day
application_widget_live_stream_views_logout	Impressions of your Live Stream plugin from users logged into Facebook	day
application_widget_live_stream_views_external_referrals	Top domains of impressions of your Live Stream plugins	day
application_widget_recommendation_views	Impressions of your Recommendation plugin	day
application_widget_recommendation_views_unique	Recommendation Plugin impressions from users logged into Facebook	day
application_widget_recommendation_views_login	Recommendation Plugin impressions from users logged into Facebook	day
application_widget_recommendation_views_login_unique	Recommendation Plugin impressions from users logged into Facebook	day
application_widget_recommendation_views_logout	Recommendation Plugin impressions from users not logged into Facebook	day
application_widget_recommendation_views_external_referrals	Top domains of impressions of your Recommendation plugins	day
application_widget_share_views	Impressions of your Share widget from users logged into Facebook	day
application_widget_share_views_unique	Impressions of your Share widget from users logged into Facebook	day
application_widget_views	Total social plugin impressions	day
application_widget_views_unique	Total social plugin impressions from users logged into Facebook	day
application_widget_views_login	Total social plugin impressions from users logged into Facebook	day
application_widget_views_login_unique	Total social plugin impressions from users logged into Facebook	day
application_widget_views_logout	Total social plugin impressions from users not logged into Facebook	day

Open Graph

Name	Description	Available Periods
application_opengraph_action_create*	Number of Open Graph Actions created by your application	day
application_opengraph_action_delete*	Number of Open Graph Actions deleted by your application	day
application_opengraph_object_create*	Number of Open Graph Objects created by your application	day
application_opengraph_object_update*	Number of Open Graph Objects updated by your application	day
application_opengraph_story_impressions*	Number of impressions of an Open Graph story	day
application_opengraph_story_click*	Number of impressions of an Open Graph story	day
application_opengraph_story_like*	Number of likes of an Open Graph story	day
application_opengraph_story_unlike*	Number of unlikes of an Open Graph story	day
application_opengraph_story_comment*	Number of comments of an Open Graph story	day
application_opengraph_story_hide*	Number of hides of an Open Graph story	day
application_opengraph_story_hide_all*	Number of times that all stories were hidden from your application	day
application_opengraph_story_report_spam*	Number of spam reports of an Open Graph story	day
application_opengraph_link_impression*	Number of impressions of an Open Graph action link	day
application_opengraph_link_click*	Number of clicks of an Open Graph action link	day
application_opengraph_timeline_impressions*	Number of impressions of an Open Graph Timeline aggregation	day
application_opengraph_timeline_spam*	Number of spam reports of an Open Graph Timeline aggregation	day
application_opengraph_timeline_clicked*	Number of clicks of an Open Graph Timeline aggregation	day

Canvas

Name	Description	Available Periods
application_canvas_views	Number of impressions of your app's canvas page	day
application_canvas_views_unique	Number of impressions of your app's canvas page from users logged into Facebook	day
application_canvas_views_login	Number of impressions of your app's canvas page from users logged into Facebook	day
application_canvas_views_login_unique	Number of impressions of your app's canvas page from users logged into Facebook	day
application_canvas_views_logout	Number of impressions of your app's canvas page from users not logged into Facebook	day
application_canvas_views_internal_referrals	Top referrers to your Canvas page on Facebook	day
application_canvas_views_external_referrals	Top referrering external domains to your Canvas page	day

Application Tabs

Name	Description	Available Periods
application_tab_views	Impressions of your app's tab on users' Profiles	day
application_tab_views_unique	Impressions of your app's tab on users' Profiles	day

API Performance

Name	Description	Available Periods
application_api_calls	Total API calls from your app	day
application_api_calls_top	Most frequent API calls from your app	day
application_api_calls_unique	Total API calls from your app	day
application_api_errors	Total API errors from your app	day
application_api_errors_rate	Average number of errors per API request from your app	day
application_api_errors_top	Most frequent API errors from your app	day
application_api_time_average	Average time for API requests from your app, in milliseconds	day
application_canvas_errors	HTTP request errors on your Canvas page	day
application_canvas_errors_rate	Average number of errors per canvas request of your app	day
application_canvas_time_average	Average HTTP response time on your Canvas page, in milliseconds	day

Stories and People talking about this

Name	Description	Available Periods
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	day, week, days_28
page_stories_by_story_type	The number of stories about your Page by story type	day, week, days_28
page_storytellers_by_story_type	The number of people talking about your Page, by story type	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_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

Page Impressions

Name	Description	Available Periods
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	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	day, week, days_28
page_impressions_by_story_type	Total impressions of stories published by a friend about your Page by story type	day, week, days_28
page_impressions_by_story_type_unique	The number of people who saw a story about your Page by story type	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_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 Engagement

Name	Description	Available Periods
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 without generating a story	day, week, days_28
page_consumptions_unique	The number of people who clicked on any of your content without generating a story	day, week, days_28
page_consumptions_by_consumption_type	The number of times people clicked on any of your content without generating a story, by type	day, week, days_28
page_consumptions_by_consumption_type_unique	The number of people who clicked on any of your content without generating a story, 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 Users

Name	Description	Available Periods
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_friends_of_fans	The number of people who are friends of the Fans of your Page (estimated). This metric will be removed on 10th July, 2013	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.

Name	Description	Available Periods
page_tab_views_login_top_unique	The number of users logged into Facebook who saw tabs on your Page	day
page_tab_views_login_top	The number of times users logged into Facebook saw tabs on your Page	day

Page Views

Name	Description	Available Periods
page_views	Page views	day
page_views_unique	Page Views from users logged into Facebook	day
page_views_login	Page Views from users logged into Facebook	day
page_views_login_unique	Page Views from users logged into Facebook	day
page_views_logout	Page views from users not logged into Facebook	day
page_views_external_referrals	Top referrering external domains sending traffic to your Page.	day

Page Posts

Name	Description	Available Periods
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 Post: Stories and People talking about this

Name	Description	Available Periods
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

Page Post: Impressions

Name	Description	Available Periods
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

Page Post: Engagement

Name	Description	Available Periods
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

Domain Content

Name	Description	Available Periods
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

Like Sources

Source	Description
page_suggestion	People who liked your Page through an invite from an admin
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
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
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

Negative Feedback Types

Type	Description
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