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"
      ]
    }
  ]
}
Example: "Sum of Daily Page Reach" in October, compared to September.

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

    fb:page_reach_total
  • Total 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_views
  • Message conversations started

    The number of times accounts messaged your business for the first time or after a period of inactivity.

    fb:page_messages_new
  • Page 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_reported
  • Posts Count

    Total number of posts on your page in the analyzed period.

    fb:page_posts_count
  • Total 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_shares
  • Total 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_comments
  • Total 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_unique
  • Post 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_engagements
  • Post 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_engagements
  • Organic 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_reach
  • Organic 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_organic
  • Paid 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_paid
  • Media 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_follows
  • Media 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_follows
  • Reels 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_views
  • Paid 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_views
  • Organic 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_views
  • Number of Reels

    Number of reels posted to the account during the analyzed period.

    fb:page_reels_count
  • Total 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_unique
  • Total 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_count
  • Average 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_watched
  • Total 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_type
  • Total 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_comments
  • Total 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_shares
  • Total 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_time
  • Page followers

    The number of followers of your Facebook Page. This is calculated as the number of follows minus the number of unfollows.

    fb:page_follows
  • New 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_follows
  • Total 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_reactions
  • Total 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_time
  • Page 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_time
  • Messaging 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_time
  • Best 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_city
  • Countries with the largest number of followers

    Countries with the largest number of followers

    fb:page_follows_by_country
  • Performance 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_type
  • Featured posts

    Posts that had the biggest impact on your audience. The reactions in the shares of your posts are not considered.

    fb:page_posts
  • Featured 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.