Metrics
Facebook metrics via API
Your customer connects their Facebook account and your product queries 40 metrics through the same endpoint as every other platform. Each metric has an id (reference_key) that goes in the request.
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-10-01",
"end": "2026-10-31",
"comparison_start": "2026-09-01",
"comparison_end": "2026-09-30",
"metrics": [
{
"id": "m1",
"reference_key": "fb:page_reach",
"component": "number_v1",
"metrics": [
"page_impressions_unique"
]
}
]
}More Facebook request examples
The same endpoint for every kind of metric. The metrics and dimensions of each item come from the platform catalog (GET /api/metrics/{integration_slug}).
Chart
Follower growth
The graph describes the evolution of the page's followers
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-10-01",
"end": "2026-10-31",
"metrics": [
{
"id": "m1",
"reference_key": "fb:follows_over_time",
"component": "chart_v1",
"metrics": [
"page_follows"
],
"dimensions": [
"date"
]
}
]
}Table
Cities with the highest number of followers
Cities with the highest number of followers
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-10-01",
"end": "2026-10-31",
"metrics": [
{
"id": "m1",
"reference_key": "fb:page_follows_by_city",
"component": "datatable_v1",
"metrics": [
"page_follows_city"
],
"dimensions": [
"city"
]
}
]
}Number
Viewers
The number of Meta Accounts that have viewed your content at least once. Content includes reels, posts, stories, live videos and ads. This metric is estimated and in development.
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-10-01",
"end": "2026-10-31",
"metrics": [
{
"id": "m1",
"reference_key": "fb:page_reach_total",
"component": "number_v1",
"metrics": [
"page_impressions_unique"
],
"dimensions": [
"total"
]
}
]
}Numbers
31 metrics
Sum of Daily Page Reach
Sum of the unique daily reach of your page or about it. If a user saw content on your page on two different days, it will be counted twice. This includes posts, check-ins, ads, social information about people who interacted with your page, for example. This metric is an approximate value.
fb:page_reachViewers
The number of Meta Accounts that have viewed your content at least once. Content includes reels, posts, stories, live videos and ads. This metric is estimated and in development.
fb:page_reach_totalTotal Media Views
The number of times any content from your Page or about your Page entered a person's screen. This includes posts, stories, ads, as well other content or information on your Page.
fb:page_media_viewsMessage conversations started
The number of times accounts messaged your business for the first time or after a period of inactivity.
fb:page_messages_newPage Reported Conversations
The number of conversations from your page that have been reported by people for reasons such as spam, or containing inappropriate content.
fb:page_messages_reportedPosts Count
Total number of posts on your page in the analyzed period.
fb:page_posts_countTotal post shares
The number of times your posts have been shared, from the time they were posted to the time the report was generated. This metric is calculated by adding up the total shares for each post listed in the "Featured Posts" table.
fb:page_posts_sharesTotal comments on posts
The number of times your posts received a comment, from the time they were posted until the time the report was generated. This metric is calculated by adding up the total comments for each post listed in the "Featured Posts" table.
fb:page_posts_commentsTotal Post Viewers
Sum of the total viewers of each of your posts for the analyzed period, from when they were posted until the time the report was generated. This metric is an approximate value. And because it is the sum of the viewers of each post, if a user saw more than one post, they will be counted more than once. This metric is calculated by adding the total viewers of each post listed in the "Featured Posts" table.
fb:page_posts_impressions_uniquePost engagement rate
The engagement rate for Facebook posts is determined by dividing the total engagement of the post by the total number of impressions of the post, multiplied by 100. This takes into account the results of any post in the selected analysis period, regardless of the date it was published. This engagement covers all interactions people have with your ads and posts while they are being displayed. It can involve actions such as reactions, comments, shares, offer redemptions, photo or video views, or link clicks.
fb:page_post_rate_engagementsPost engagement
The number of times people engaged with your posts during the reporting period, regardless of when they were posted, through reactions, comments, shares, and more.
fb:page_post_engagementsOrganic Post Viewers
Sum of the organic viewers of each of your posts from the analyzed period when they were posted until the time the report was generated. This metric is an approximate value. And because it is the sum of the viewers of each post, if a user saw more than one post, they will be counted more than once. This metric is calculated by adding the organic viewers of each post listed in the "Featured Posts" table.
fb:page_post_organic_reachOrganic Page Media Views
The number of times a post or story content from or about your Page appeared on a person's screen through unpaid distribution.
fb:page_media_views_organicPaid Page Media Views
The number of times a post or story content from or about your Page appeared on a person's screen through paid distribution.
fb:page_media_view_paidMedia Views of Non Follows
The number of times a post or story content from or about your Page appeared on a person's screen who does not follow your Page.
fb:page_media_view_non_followsMedia Views of Follows
The number of times a post or story content from or about your Page appeared on a person's screen who follows your Page.
fb:page_media_view_followsReels Views
The number of times your videos were viewed during the analyzed period, regardless of whether the content was published for at least 3 seconds or nearly its full duration if it is shorter than 3 seconds. This value counts each video view and excludes replays.
fb:total_video_viewsPaid views of Reels
The number of times your promoted videos were viewed during the analyzed period, regardless of when the content was published, for at least 3 seconds or for almost their entire duration if they are less than 3 seconds. This value counts each view of a video and excludes replays.
fb:paid_video_viewsOrganic Reels views
The number of times your videos were viewed during the analyzed period, regardless of when the content was published, through organic reach, for at least 3 seconds or almost their total duration if they are shorter than 3 seconds. This value counts each view of a video and excludes replays.
fb:organic_video_viewsNumber of Reels
Number of reels posted to the account during the analyzed period.
fb:page_reels_countTotal Reels Viewers
Sum of the viewers of each reel posted in the analyzed period, from its posting to the time the report was generated. This metric is an approximate value. And because it is the sum of the viewers of each reel, if a user viewed more than one reel, it will be counted more than once. This metric is calculated by adding the viewers of each reel listed in the "Featured Reels" table.
fb:post_impressions_uniqueTotal Reel Views
Sum of plays for each reel posted in the analysis period from when it was posted until the time the report was generated. Plays are the number of times your reel starts playing after an impression has already been counted. This metric counts reel sessions with 1 millisecond or more of playtime. This metric excludes replays. This metric is calculated by adding the number of plays for each reel listed in the "Featured Reels" table.
fb:blue_reels_play_countAverage viewing time of reels
The average play time of your video. This metric is calculated by dividing the watch time by the number of initial views. An initial view is when your video starts playing for the first time in a video session.
fb:post_video_avg_time_watchedTotal likes on Reels
Sum of organic likes for each Reel posted in the analyzed period, from when it was posted until the time the report was generated. This metric is calculated by adding the likes for each Reel listed in the "Featured Reels" table.
fb:post_video_likes_by_reaction_typeTotal comments on Reels
Sum of comments received on each Reel published during the analyzed period, considering comments received from the time of posting until the report was generated. This metric is calculated by summing the comments for each Reel listed in the "Featured Reels" table.
fb:post_video_social_actions_commentsTotal Reels shares
Sum of the shares of each Reel published during the analyzed period, from the time of posting until the report was generated. This metric is calculated by summing the shares of each Reel listed in the "Featured Reels" table.
fb:post_video_social_actions_sharesTotal viewing time of Reels
The total number of minutes your reels have been viewed from when they were posted until the time the report is generated, including replays.
fb:post_video_view_timePage followers
The number of followers of your Facebook Page. This is calculated as the number of follows minus the number of unfollows.
fb:page_followsNew page followers
Net change in the number of page followers. The calculation is performed by subtracting the number of followers on the last day of the analysis period from the total number of followers on the day prior to the first day of analysis.
fb:net_page_followsTotal post reactions
The number of times your posts received a reaction from the time they were posted until the time the report was generated. Reactions to shares of your posts are not taken into account. This metric is calculated by adding up the total reactions for each post listed in the "Featured Posts" table.
fb:page_posts_all_reactionsTotal reactions of the period
Total number of reactions to your content (including ads) during the analyzed period, regardless of when the content was published. The reactions button on a post allows people to share different reactions to your content: Like, Love, Haha, Wow, Sad, or Angry. The content can have formats such as posts and reels, among others.
fb:page_all_reactions
Charts
4 metrics
Follower growth
The graph describes the evolution of the page's followers
fb:follows_over_timePage views evolution
The graph shows the evolution of the page's total unique viewers, organic media views, and paid media views over time. Following the Meta API migration in June 2026, the Organic and Paid lines represent total media views broken down by distribution type, not unique viewers.
fb:reach_over_timeMessaging conversations initiated over time
The number of times accounts messaged your business for the first time or after a period of inactivity, grouped by day.
fb:page_messages_new_over_timeBest day for posts
This chart shows which day performed best considering the Impressions of posts on your Facebook Page.
fb:page_fans_online_per_day
Tables
5 metrics
Cities with the highest number of followers
Cities with the highest number of followers
fb:page_follows_by_cityCountries with the largest number of followers
Countries with the largest number of followers
fb:page_follows_by_countryPerformance by Post Types
Performance on each post type. With this table you can better understand which posts are performing better and engaging your followers.
fb:page_posts_performance_by_typeFeatured posts
Posts that had the biggest impact on your audience. The reactions in the shares of your posts are not considered.
fb:page_postsFeatured Reels
Reels that had the biggest impact on your audience.
fb:page_reels
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
