Skip to main content
Skip table of contents

Facebook Insights

Overview

endor/Partner

Facebook

Version

v19.0

API Documentation

https://developers.facebook.com/docs/graph-api/

https://developers.facebook.com/docs/graph-api/changelog/versions/

Sunset Date

Marketing API: February 4th, 2025

Channel(s)

Refresh Time (CST)

3am

Default backfill

Most metrics will update once every 24 hours.

Metrics retrieved using third-party APIs can take up to 3 days from being reported to Facebook (not from the time they occur).

Alli Data Library

(error)

Getting Started

Required Authorization

Facebook Insights requires a Facebook account with access to Facebook Business Manager. You can check which profiles you have access to by visiting business.facebook.com.

  1. Once you have an account with Business Manager access, click the Request Facebook Insights Access button.

  2. The next step is to select the username and report type from the Additional Configuration Needed section.

  3. Make sure to click the Next button to save your selection.

Limitations

  1. You must be a page manager to be able to pull data.

Define Your Data:

Page Fan Lifetime

Dimensions

Name

Type

Description

Field Name

Date

Date

date

Page Id

String

pageid

Metrics

Name

Type

Description

Field Name

Page Fans

Number

page_fans

Page Fan by Locale Lifetime

Dimensions

Name

Type

Description

Field Name

Date

Date

date

Page Id

String

pageid

Language

String

language

Country

String

country

Metrics

Name

Type

Description

Field Name

Page Fans

Number

page_fans_locale

Page Fan by City Lifetime

Dimensions

Name

Type

Description

Field Name

Page Id

String

pageid

City

String

city

Metrics

Name

Type

Description

Field Name

Page Fans

Number

page_fans_city

Page Fan by Country Lifetime

Dimensions

Name

Type

Description

Field Name

Date

Date

date

Page Id

String

pageid

Country

String

country

Metrics

Name

Type

Description

Field Name

Page Fans

Number

page_fans_country

Page Fan by Gender Age Lifetime

Dimensions

Name

Type

Description

Field Name

Date

Date

date

Page Id

String

pageid

Gender/Age

String

gender_age

Metrics

Name

Type

Description

Field Name

Page Fans

Number

undefined

page_fans_gender_age

Page Fan Online Day

Dimensions

Name

Type

Description

Field Name

Date

Date

date

Page Id

String

pageid

hour

Number

hour

Metrics

Name

Type

Description

Field Name

Page Fans Online

Number

undefined

page_fans_online

Page Metrics by Day

Dimensions

Name

Type

Description

Field Name

Date

Date

date

Page Id

String

pageid

Metrics

Name

Type

Description

Field Name

Lifetime Page Fans

Number

page_fans

Daily New Likes Unique

Number

page_fan_adds_unique

Daily New Likes

Number

page_fan_adds

Daily New likes by paid

Number

page_fan_adds_by_paid

Daily New likes by organic

Number

page_fan_adds_by_organic

Daily Unlikes

Number

page_fan_removes_unique

Daily Unlikes

Number

page_fan_removes

Daily Logged-in Page Views

Number

page_views_login

Daily Non-logged-in Page Views

Number

page_views_logout

Daily Total Reach

Number

page_impressions_unique

Daily Total Impressions

Number

page_impressions

Daily Paid Reach

Number

page_impressions_paid_unique

Daily Paid Impressions

Number

page_impressions_paid

Daily Organic Reach

Number

page_impressions_organic_unique

Daily Organic impressions

Number

page_impressions_organic

Daily Viral Reach

Number

page_impressions_viral_unique

Daily Viral impressions

Number

page_impressions_viral

Daily Reach of page posts

Number

page_posts_impressions_unique

Daily Total Impressions of your posts

Number

page_posts_impressions

Daily Paid Reach of Page posts

Number

page_posts_impressions_paid_unique

Daily Paid impressions of your posts

Number

page_posts_impressions_paid

Daily Organic Reach of Page posts

Number

page_posts_impressions_organic_unique

Daily Organic impressions of your posts

Number

page_posts_impressions_organic

Daily Viral Reach of page posts

Number

page_posts_impressions_viral_unique

Daily Viral impressions of your posts

Number

page_posts_impressions_viral

Daily Total Consumers

Number

page_consumptions_unique

Daily Page consumptions

Number

page_consumptions

Daily Daily count of fans online

Number

page_fans_online_per_day

Daily Page Engaged Users

Number

page_engaged_users

Daily Logged-in Page Views

Number

page_views_unique

Page Video Views

Number

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

page_video_views

Paid Page Video Views

Number

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

page_video_views_paid

Organic Page Video Views

Number

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

page_video_views_organic

Page Video Views Autoplayed

Number

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

page_video_views_autoplayed

Page Video Views Clicked To Play

Number

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

page_video_views_click_to_play

Page Video Views Unique

Number

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

page_video_views_unique

Page Video Repeat Views

Number

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

page_video_repeat_views

Page Video Views (30s)

Number

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

page_video_complete_views_30s

Paid Page Video Views (30s)

Number

page_video_complete_views_30s_paid

Organic Video Views (30s)

Number

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

page_video_complete_views_30s_organic

Page Video Views (30s Autoplayed)

Number

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

page_video_complete_views_30s_autoplayed

Page Video Views (30s click to play)

Number

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

page_video_complete_views_30s_click_to_play

Page Video Views (30s Unique)

Number

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

page_video_complete_views_30s_unique

Post Report Lifetime

Dimensions

Name

Type

Description

Field Name

Date

Date

date

Page Id

String

pageid

Post ID

String

postid

Metrics

Name

Type

Description

Field Name

Post Content

String

post_title

Post URL

String

post_url

Post Type

String

post_type

Post Creation Date

String

post_creation_time

Post Updated Date

String

post_updated_time

Likes

Number

likes

Comments

Number

comments

Shares

Number

share

Unique Likes

Number

unique_likes

Unique Comments

Number

unique_comments

Unique Shares

Number

unique_share

Engaged Fans

Number

People who have liked your page and engaged with your post

post_engaged_fan

Lifetime Talking About This

Number

post_story_adds_unique

Story Adds

Number

post_story_adds

Total Reach

Number

post_impressions_unique

Total Impressions

Number

post_impressions

Paid Reach

Number

post_impressions_paid_unique

Paid Impressions

Number

post_impressions_paid

organic reach

Number

post_impressions_organic_unique

Organic Impressions

Number

post_impressions_organic

viral reach

Number

post_impressions_viral_unique

Viral Impressions

Number

post_impressions_viral

reach by Followers

Number

post_impressions_fan_unique

Impressions by people who have liked your Page

Number

post_impressions_fan

Lifetime Paid reach of a post by people who like your Page

Number

post_impressions_fan_paid_unique

Paid Impressions by people who have liked your Page

Number

post_impressions_fan_paid

Consumers

Number

post_consumptions_unique

Consumptions

Number

post_consumptions

Lifetime Hide All Clicks

Number

The number of people who clicked hide all on your posts.

post_hide_all_clicks

Lifetime Hide Clicks

Number

The number of people who clicked hide on your post.

post_hide_clicks

Lifetime Unique Hide All Clicks

Number

The number of people who clicked hide all on your posts.

post_hide_all_clicks_unique

Lifetime Unique Hide Clicks

Number

The number of people who clicked hide on your post.

post_hide_clicks_unique

Lifetime Negative feedback

Number

post_negative_feedback_unique

Lifetime Negative Feedback from Users

Number

post_negative_feedback

Lifetime Talking About This

Number

post_storytellers

Lifetime Engaged Users

Number

post_engaged_users

Stories

Number

post_stories

Lifetime Average time video viewed

Number

Lifetime: Average time video viewed (Total Count)

post_video_avg_time_watched

Lifetime Total Video Views

Number

Lifetime: Total number of times your video was viewed for more than 3 seconds. (Total Count)

post_video_views

Lifetime Unique Video Views

Number

Lifetime: Number of unique people who viewed your video for more than 3 seconds. (Unique Users)

post_video_views_unique

Lifetime Auto-Played Video Views

Number

Lifetime: Number of times your video started automatically playing and people viewed it for more than 3 seconds. (Total Count)

post_video_views_autoplayed

Video Views (10s unique)

undefined

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

post_video_views_10s_unique

Video Views (10s autoplayed)

undefined

Number of times your video started playing automatically and people viewed it for 10 seconds or to the end, whichever happened first

post_video_views_10s_autoplayed

Video Views (10s Clicked To Play)

undefined

Number of times people clicked to play your video and viewed it for 10 seconds or to the end, whichever happened first

post_video_views_10s_clicked_to_play

Video Views (10s organic)

undefined

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

post_video_views_10s_organic

Video Views (10s paid)

undefined

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

post_video_views_10s_paid

Video Views (10s sound on)

undefined

Number of times your video was viewed with sound on for 10 seconds or viewed to the end, whichever happened first

post_video_views_10s_sound_on

Video Views Sound On

undefined

Number of times your video was viewed with sound on for 3 seconds or viewed to the end, whichever happened first

post_video_views_sound_on

Video View Time

undefined

Total time (in milliseconds) video has been viewed

post_video_view_time

Video View Time Organic

undefined

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

post_video_view_time_organic

Lifetime Clicked-to-Play Video Views

Number

Lifetime: Number of times people clicked to play your video and viewed it more than 3 seconds. (Total Count)

post_video_views_clicked_to_play

Lifetime Organic Video Views

Number

Lifetime: Number of times your video was viewed for more than 3 seconds without any paid promotion. (Total Count)

post_video_views_organic

Lifetime Unique Organic Video Views

Number

Lifetime: Number of times your video was viewed for more than 3 seconds without any paid promotion. (Unique Users)

post_video_views_organic_unique

Lifetime Organic views to 95%

Number

Lifetime: Number of times your video was viewed to 95% of its length without any paid promotion. (Total Count)

post_video_complete_views_organic

Lifetime Unique Organic views to 95%

Number

Lifetime: Number of times your video was viewed to 95% of its length without any paid promotion. (Unique Users)

post_video_complete_views_organic_unique

Lifetime Paid Video Views

Number

Lifetime: Number of times your video was viewed more than 3 seconds after paid promotion. (Total Count)

post_video_views_paid

Lifetime Unique Paid Video Views

Number

Lifetime: Number of times your video was viewed more than 3 seconds after paid promotion. (Unique Users)

post_video_views_paid_unique

Video Length

Number

Length of a video post (in milliseconds)

post_video_length

Lifetime Paid views to 95%

Number

Lifetime: Number of times your video was viewed to 95% of its length after paid promotion. (Total Count)

post_video_complete_views_paid

Lifetime Unique Paid views to 95%

Number

post_video_complete_views_paid_unique

Lifetime Total 30-Second Views

Number

Lifetime: Total number of times your video was viewed for 30 seconds or viewed to the end, whichever came first. (Total Count)

post_video_complete_views_30s

Lifetime Unique 30-Second Views

Number

Lifetime: Number of unique people who viewed your video for 30 seconds or to the end, whichever came first. (Unique Users)

post_video_complete_views_30s_unique

Lifetime Auto-Played 30-Second Views

Number

Lifetime: Number of times your video started automatically playing and people viewed it for 30 seconds or to the end, whichever came first. (Total Count)

post_video_complete_views_30s_autoplayed

Lifetime Clicked-to-Play 30-Second Views

Number

Lifetime: Number of times people clicked to play your video and viewed it for 30 seconds or to the end, whichever came first. (Total Count)

post_video_complete_views_30s_clicked_to_play

Lifetime Organic 30-Second Views

Number

Lifetime: Number of times your video was viewed for 30 seconds or viewed to the end, whichever came first, without a paid promotion. (Total Count)

post_video_complete_views_30s_organic

Lifetime Paid 30-Second Views

Number

Lifetime: Number of times your video was viewed for 30 seconds or viewed to the end, whichever came first, after a paid promotion. (Total Count)

post_video_complete_views_30s_paid

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.