Meta API Suite

Purpose of the Report:
This document serves as an expert-level developer brief, providing an in-depth inventory of metrics, dimensions, and essential access details for read-only reporting across key Meta APIs. Its primary objective is to equip development teams with the necessary technical information to facilitate seamless and effective API integrations with their reporting platforms.1

Scope and Structure:
The report covers a wide array of Meta services, categorized into Social Integrations, Business Messaging, and Marketing & Commerce. Each API within these categories will be analyzed for its reporting capabilities, specifically focusing on available metrics, dimensions, and the critical API access prerequisites: versioning, authentication (including token types and permissions), and rate limiting [User Query].

Importance of API Access Details:
Successful and robust API integration hinges on a thorough understanding of Meta's API access protocols. This includes adherence to API versioning to prevent breaking changes, correct implementation of authentication mechanisms to ensure secure data access, and awareness of rate limits to maintain application stability and avoid service disruptions. This report will detail these aspects for each relevant API.2

Overview of the Graph API:
The Meta Graph API is the fundamental way applications interact with the Facebook social graph, enabling programmatic querying of data, posting content, managing ads, and performing a wide variety of other tasks. It is an HTTP-based API, making it compatible with any language that possesses an HTTP library.7 Understanding its core structure—nodes (objects like Users, Pages, Posts), edges (connections between objects, like a Page's Posts), and fields (attributes of objects, like a Post's message content)—is crucial, as many other Meta APIs are extensions of, or interact directly with, the Graph API.7 For instance, a request to fetch a Page's feed is a query to the feed edge of a Page node.

A. API Versioning:

General Principles: Meta API versions are typically released on a quarterly basis. Each version is guaranteed to operate for a minimum of two years from its release date. When an API version is deprecated and becomes unusable (generally two years after the release of the next version), calls made to that expired version will automatically default to the next oldest, still-usable version.3 This policy aims to provide developers with a window to adapt to changes while allowing Meta to evolve its platform.

Specifying Versions: It is strongly recommended to explicitly specify the API version in all calls. This is done by prefixing the version number to the request path (e.g., /v22.0/user_id/accounts).3 If no version is specified, the call defaults to the oldest available version, which can lead to unexpected behavior or reliance on soon-to-be-deprecated features.3 The latest version of the Graph API noted in the documentation is v22.0.7

Impact on Reporting: For reporting integrations, consistent data structures and metric definitions are paramount. Changes between API versions can affect available fields, the definition or calculation of metrics, or even endpoint behavior. Therefore, developers building reporting solutions must diligently monitor the Graph API Changelog and proactively plan for migrating their integrations to newer, supported versions to ensure data accuracy and prevent service disruptions.3 The two-year support window for each version offers a manageable timeframe for such updates, but the quarterly release cadence implies a continuous need for awareness and potential adjustments to reporting logic to leverage new capabilities or comply with deprecations.

SDK Versioning: SDKs for various platforms (JavaScript, iOS, Android) are typically tied to the API version available at their release. Upgrading an SDK often implies upgrading the API version used by default. However, SDKs usually provide mechanisms to override the default and specify an older, still-available API version if necessary.3

B. Authentication & Authorization:

Access Tokens: Access tokens are fundamental to interacting with the Graph API. They are opaque strings that identify an app, a user, or a Page, and they are required for almost all API calls. Tokens serve two primary functions: they allow an app to access a user's information without needing the user's password, and they enable Meta to identify the calling app, the user on whose behalf the call is made (if applicable), and the specific data permissions granted to the app by that user.4

Types of Access Tokens Relevant to Reporting:

User Access Token: Obtained when a user logs into an app and grants permissions. These are used for actions performed on behalf of that specific user. User tokens can be short-lived (expiring in about an hour or two) or long-lived (typically lasting about 60 days). For applications with Standard access to the Marketing API, long-lived tokens may not have a fixed expiry time but can still be invalidated.4 For ongoing reporting tasks, short-lived tokens are impractical due to frequent re-authentication needs.

App Access Token: Used for requests made on behalf of the app itself, such as fetching app insights or managing test users. These are generated using the App ID and App Secret and are intended for server-to-server calls. App access tokens should never be exposed on the client-side, as this would compromise the App Secret.4

Page Access Token: Necessary for managing Facebook Pages and reading Page-specific data, including Page Insights. A Page access token is obtained by a Page admin granting the app relevant Page permissions; the app then uses a User access token (with these permissions) to retrieve the Page access token for that specific Page.4 These tokens are unique to each Page, app user, and app.

System User Access Token: Represents a server or software making API calls to assets owned or managed by a Business Manager. These tokens are ideal for automated, backend processes like regular data fetching for reporting systems, as they can be long-lived and are not tied to a specific human user's session.11

Permissions: Permissions are granular authorizations granted by users (or admins for Pages/business assets) that define what data an app can access or what actions it can perform. For read-only reporting, key permissions include read_insights (for general Page, app, and domain insights), pages_read_engagement (for detailed Page content and engagement data), instagram_manage_insights (for Instagram account and media insights), ads_read (for accessing ad performance data via the Marketing API), and threads_manage_insights (for Threads profile and post insights).2 Requesting only necessary permissions is crucial, as over-requesting is a common reason for App Review rejection.2

Access Levels (Standard vs. Advanced): Meta defines access levels that impact the scope of data an app can access.

Standard Access: By default, apps have Standard Access. With this level, permissions can only be requested from app users who have an explicit role on the app (e.g., admin, developer, tester). Features are only active for these roled users. This significantly limits the data pool for reporting purposes if the goal is to analyze data from a general user base.6

Advanced Access: To access data from users who do not have a role on the app, Advanced Access for the required permissions is necessary. Obtaining Advanced Access typically requires Business Verification and may involve an App Review process for each permission and feature. Consumer apps must also be in Live mode to use Advanced Access permissions with non-roled users.6 For any comprehensive reporting platform, securing Advanced Access for relevant insights permissions is a critical step.

Secure Token Management: It is imperative to manage access tokens securely. Tokens should be transferred over HTTPS. App secrets must be rigorously protected and never embedded in client-side code. Meta provides an Access Token Debugger tool to inspect tokens and their properties.4 For server-to-server calls, using an appsecret_proof (a SHA256 hash of the access token using the app secret as the key) can enhance security by verifying that requests originate from a trusted server.7

The selection of the correct access token type (e.g., Page or System User token for backend reporting services), coupled with the necessary permissions and Advanced Access level, directly determines the breadth and depth of data that can be retrieved for reporting purposes. Without these, a reporting platform's utility would be severely constrained.

C. Rate Limiting:

General Overview: Meta employs rate limits to ensure the stability and fair usage of its APIs. These limits restrict the number of API calls an application or user can make within a specific time window. Exceeding these limits results in temporary blocking of requests (throttling).2

Types of Rate Limits:

Platform Rate Limits: These apply to general Graph API calls and the Instagram Basic Display API. Limits can be at the application level (calculated based on the number of users, e.g., Calls within one hour = 200 * Number of Users) or at the individual user level. A user's call count is aggregated across all apps they use.2

Business Use Case (BUC) Rate Limits: These are more complex and apply to specific APIs like the Marketing API, Instagram Platform API (Graph API for Instagram), and Pages API (when using Page or System User access tokens). BUC limits are often tied to the specific functionality (e.g., Ads Insights, Ads Management, Custom Audiences) and can involve factors beyond simple call counts, such as CPU time and total processing time consumed by requests. The quota for Marketing API requests, for example, depends on the app's Marketing API Access Tier (development_access vs. standard_access achieved via Advanced Access to the Ads Management Standard Access feature).2

Monitoring Usage: API responses often include HTTP headers like X-App-Usage (for Platform Rate Limits) or X-Business-Use-Case-Usage (for BUC Rate Limits). These headers provide JSON-formatted data detailing current usage against the limits, including call_count, total_cputime, and total_time percentages.2 For BUC limits, the X-Business-Use-Case-Usage header also includes estimated_time_to_regain_access (in minutes) if throttling is active.2

Handling Throttling: When rate limits are exceeded, the API will return specific error codes (e.g., 4, 17 for Platform limits; 80000-series for BUC limits). Applications must implement robust error handling, including retry mechanisms with exponential backoff strategies, to manage throttling gracefully. Checking the estimated_time_to_regain_access can guide when to resume calls.2

For a reporting platform that needs to make frequent read-only calls, particularly to APIs governed by BUC rate limits (like Marketing API for Ads Insights or Instagram Insights), proactive management of these limits is essential. The limits can be dynamic (e.g., Ads Insights limits are influenced by the number of active ads 2). Therefore, designing data ingestion processes to operate within these constraints, possibly by distributing calls over time or prioritizing critical data, is a key architectural consideration.

D. Error Handling & Pagination:

Common Error Structure: Failed API requests typically return a JSON response containing fields such as message (a human-readable description), code (an error code), error_subcode (for more specific information), error_user_msg (localized message for display to the user), error_user_title (localized dialog title), and fbtrace_id (an internal support identifier crucial for bug reporting).5

Key Error Codes for Reporting Integrations:

102 (API Session / OAuthException): Often indicates an invalid or expired access token. The application should initiate a re-authentication flow for the user or refresh the token if possible.5

4 (API Too Many Calls) / 17 (API User Too Many Calls): Signals that platform rate limits have been hit. The application should pause requests and retry later, respecting backoff strategies.5

10 / 200-299 (API Permission Denied): The app lacks the necessary permission to access the requested data or perform the action. The user may need to grant additional permissions, or the app may need to request them via App Review.5

80000-series errors: Indicate Business Use Case rate limits have been exceeded (e.g., 80001 for Page Insights, 80000 for Ad Account Insights). Similar to platform rate limits, implement backoff and check usage headers.12

190 (Access token has expired): A specific OAuthException indicating token expiry; requires obtaining a new token.5

3 (API Method): Often indicates a capability or permissions issue beyond simple grant/revoke, possibly relating to feature access or object ownership.5

Pagination: When an API endpoint returns a list of items (e.g., a Page's posts, insights data points over time), the results are typically paginated to manage response size and performance. The API response will include a paging object. This object contains cursors (with before and after values, which are opaque strings used to navigate) and often next and previous URLs. To retrieve all data, the application must follow these next links until no more next link is provided.7

Building a reliable reporting integration necessitates robust error handling and complete support for cursor-based pagination. The system must be capable of identifying different error types (e.g., transient issues like rate limiting versus persistent issues like permission denial) and reacting appropriately (e.g., retrying with backoff, alerting an administrator, or gracefully degrading functionality). Failing to correctly implement pagination will result in incomplete datasets and, consequently, inaccurate reports.

E. Batching & Field Expansion for Reporting:

Batch Requests: The Graph API supports batch requests, allowing an application to send multiple distinct API operations (up to 50) in a single HTTP call. This can improve efficiency by reducing network latency from multiple HTTP round trips.7 For example, fetching insights for several different Page posts could be combined into one batch request. It is important to note that each operation within a batch request is still counted individually towards the relevant rate limits.7

Field Expansion: This powerful feature allows developers to customize the data returned by a query, retrieving nested objects and specific fields in a single request. For example, one could request a Page's information along with its five most recent posts, and for each of those posts, retrieve their message content and the number of likes (e.g., fields=name,fan_count,posts.limit(5){message,likes.summary(true)}). Field expansion is highly beneficial for reporting as it enables fetching precisely the required data, reducing over-fetching, minimizing the amount of data transferred, and simplifying client-side data processing.7

For reporting systems, batching can be advantageous when needing to retrieve similar, discrete pieces of information (e.g., daily reach for multiple ad campaigns). Field expansion, on the other hand, is more suited for shaping the response of a single primary query to include related data from connected objects, thereby creating a more complete data snapshot with fewer API calls. Both techniques contribute to more efficient data retrieval strategies.

A. Facebook Pages API

Overview of Page Insights: The Facebook Pages API provides extensive data regarding a Facebook Page's performance, audience demographics, content engagement, and reach. Insights are primarily accessed through the /{page-id}/insights endpoint, where specific metrics and periods are requested.10 Data is typically available for Pages with 100 or more likes, and most metrics are updated daily, with a historical data availability of up to two years. When querying with since and until parameters, a maximum of 90 days of insights can be viewed at once.13

Metrics:

Page-Level Aggregates: These metrics provide an overall view of Page performance over specified periods (day, week, days_28). Key examples include page_impressions (total, unique, paid, organic, viral), page_impressions_unique, page_post_engagements, page_fan_adds_unique, page_video_views, page_total_actions (CTA clicks), and page_fans (total likes).13

Post-Level Lifetime Metrics: These metrics provide performance data for individual Page posts, typically aggregated over the lifetime of the post. Examples include post_impressions (total, unique, paid, organic, viral), post_impressions_unique, post_clicks, post_consumptions (clicks without generating a story), post_engaged_users, and various reaction counts (e.g., post_reactions_like_total, post_reactions_love_total).13

Story-Related Metrics: For stories created about Page posts (e.g., a user sharing a Page's post to their own story), metrics like post_activity_by_action_type and post_activity_by_action_type_unique are available.13

Dimensions:

The primary dimension for time-series data is period (e.g., day, week, days_28). For post-level metrics, lifetime is common.13

Metrics like post_activity_by_action_type can be broken down by story types such as checkin, fan (Page like), mention, page post (share of a Page post), user post (user posting on Page).13

Consumption metrics like post_clicks_by_type can be broken down by types such as link_clicks, photo_view, video_view.19

Demographic dimensions such as page_fans_locale, page_fans_city, and page_fans_country are available for audience analysis, typically requiring data for 100 or more people.13

API Access Details:

Versioning: Page Insights follow the general Graph API versioning scheme. Example calls in documentation often use the latest available version, such as v22.0.13

Authentication: A Page access token is required. The user who generated the access token (or whose token was used to obtain the Page token) must have the ANALYZE task permission on the target Page.9

Permissions: The pages_read_engagement and read_insights permissions are essential for accessing Page Insights data.13

Rate Limits: Calls to Page Insights are subject to Business Use Case Rate Limits when a Page access token or System User access token is used. Error code 80001 specifically indicates that the Page-level rate limit has been exceeded.2

A critical aspect for developers integrating Page Insights is distinguishing between Page-level aggregate metrics, which provide performance summaries over defined periods, and Post-level metrics, which usually reflect lifetime performance of individual content pieces. This distinction affects how data is queried (e.g., /{page-id}/insights vs. /{post-id}/insights) and how the period parameter is applied. The requirement for the ANALYZE task for the token-providing user underscores the role-based access control inherent in Facebook Page management.

B. Instagram Platform API

Overview of Instagram Insights: The Instagram Platform provides analytics for Instagram Professional Accounts (Business or Creator profiles) and their media content (posts, Stories, Reels). Data access can be through graph.instagram.com (using an Instagram User access token obtained via Business Login for Instagram) or graph.facebook.com (using a Facebook User access token via Facebook Login for Business, typically when the Instagram account is connected to a Facebook Page).21

Account-Level Metrics (IG User Insights):

These are retrieved using the /{ig-user-id}/insights endpoint.22

Key metrics include reach (unique accounts that saw any content), impressions (total times content was seen - deprecated for media created after July 2, 2024, in v22.0+ 24), profile_views, website_clicks, email_contacts, phone_call_clicks, get_directions_clicks (these latter contact-related metrics are often grouped under profile_links_taps with a contact_button_type breakdown 23), follower_count (derived from follower_demographics), accounts_engaged, likes (on account's content), comments (on account's content), saved (account's content), shares (account's content).22

Demographic insights such as follower_demographics (age, city, country, gender of followers) and engaged_audience_demographics are available, typically requiring the account to have at least 100 followers or engagements respectively.23

Media-Level Metrics (IG Media Insights - Posts, Stories, Reels):

These are retrieved using the /{ig-media-id}/insights endpoint for individual media objects.22

For general posts and Reels, metrics include engagement (defined as likes + comments for posts/Reels), impressions (deprecated as above), reach, saved, comments, likes, shares, and video_views (for video content including Reels).22

For Stories, specific metrics include replies, and navigation actions like exits, taps_forward, taps_back, next_story. These navigation actions are typically accessed via the navigation metric combined with the story_navigation_action_type breakdown.24

For Reels, specific metrics like plays (number of times reel starts to play, excluding replays - deprecated for v22.0+ 24), clips_replays_count (number of replays - deprecated for v22.0+ 24), ig_reels_avg_watch_time, and ig_reels_video_view_total_time are available.24

Dimensions:

Account Insights: The period parameter (usually day for time-series, or lifetime for some totals) is common. For demographic metrics, a timeframe parameter (e.g., last_30_days, this_month) is used instead of since/until. Breakdowns like age, city, country, gender apply to demographic metrics. For engagement or reach metrics, breakdowns like media_product_type (FEED, STORY, REELS, AD) or follow_type (FOLLOWER, NON_FOLLOWER) can be used.23

Media Insights: Breakdowns are key here, such as action_type (e.g., BIO_LINK_CLICKED, CALL) for the profile_activity metric, and story_navigation_action_type (e.g., SWIPE_FORWARD, TAP_EXIT) for the navigation metric on Stories.24

API Access Details:

Versioning: Follows the general Graph API versioning (e.g., v22.0 is referenced 23). It's crucial to note the deprecation of impressions for newly created media, and plays / clips_replays_count for Reels in v22.0 and later versions, with full deprecation for all versions on April 21, 2025.24

Authentication & Permissions:

Instagram API with Instagram Login: Requires an Instagram User access token. Necessary permissions are instagram_business_basic and instagram_business_manage_insights.22

Instagram API with Facebook Login: Requires a Facebook User access token. Necessary permissions are instagram_basic, instagram_manage_insights, and pages_read_engagement. If the user's role on the linked Facebook Page was granted via Business Manager, ads_management or ads_read permissions are also required.22

Rate Limits: Instagram Platform API calls are subject to Business Use Case Rate Limits.2

The distinction between account-level insights (overall performance) and media-specific insights (performance of individual content pieces) is fundamental for structuring reporting queries. Stories and Reels are generally treated as types of media, and their specific insights are accessed via the media insights endpoint. The announced deprecations for key metrics like impressions and some Reels-specific metrics represent a significant consideration for developers, requiring adaptation to alternative or newer metrics to maintain reporting continuity and accuracy. The availability of two distinct authentication paths (direct Instagram Login versus Facebook Login for connected accounts) provides flexibility but also introduces an additional layer of complexity in integration design.

C. Threads API

Overview of Threads Insights: The Threads API provides capabilities to read insights data related to a user's own Threads profile and their individual published threads (posts). This allows for analysis of content performance and audience engagement on the platform.28

User Insights (/{threads-user-id}/threads_insights):

These metrics provide an aggregated view of performance at the profile level. Available metrics include:

views: The number of times the user's profile was viewed. This is a time-series metric.28

likes: The total number of likes received on the user's posts.28

replies: The total number of top-level replies received on the user's posts.28

reposts: The total number of times the user's posts were reposted.28

quotes: The total number of times the user's posts were quoted.28

followers_count: The user's total number of followers on Threads. This metric does not support since and until parameters.28

follower_demographics: Provides demographic characteristics of followers, such as country, city, age, and gender distribution. This metric also does not support since and until parameters and requires the profile to have at least 100 followers.28

Media Insights (/{threads-media-id}/insights):

These metrics provide performance data for individual threads (posts or replies). Available metrics include:

views: The number of times the specific thread was played or displayed. This metric is noted as being in development.28

likes: The number of likes on the specific thread.28

replies: The number of replies on the specific thread. If the media is a root post, this includes all replies; if it's a reply itself, it includes only direct replies to that reply.28

reposts: The number of times the specific thread was reposted.28

quotes: The number of times the specific thread was quoted.28

shares: The number of shares of the specific thread. This metric is noted as being in development.28

Dimensions:

User Insights: Parameters include metric (a comma-separated list of desired metrics), since and until (UNIX timestamps defining a date range, with the earliest supported timestamp being 1712991600, corresponding to April 13, 2024). The follower_demographics metric accepts a breakdown parameter, which can be one of country, city, age, or gender.28

Media Insights: The primary parameter is metric (a comma-separated list of desired metrics).28

API Access Details:

Versioning: While not explicitly detailed for Threads Insights in the provided materials, it is generally assumed to follow the overall Graph API versioning practices.

Authentication: API calls require an appropriate access token.28

Permissions: Two key permissions are required: threads_basic (necessary for all Threads API calls) and threads_manage_insights (specifically required for making GET requests to the insights endpoints).28

Rate Limits: Calls to the Threads API are counted against the calling app's call count. The limit is calculated as: Calls within 24 hours = 4800 * Number of Impressions, where "Number of Impressions" is the number of times any content from the app user's Threads account has entered a person's screen within the last 24 hours. There are also CPU time limits. Additionally, there are specific publishing limits: Threads profiles are limited to 250 API-published posts (carousels count as one) and 1,000 replies within a 24-hour moving period. These publishing limits can be checked via the /{threads-user-id}/threads_publishing_limit endpoint.30

The Threads API insights functionality is relatively new, and the "in development" status of certain metrics like media views and shares suggests that the reporting capabilities are still evolving. The unique rate-limiting mechanism, which is tied to content impressions, is a significant factor for developers to consider, especially if their application integrates both content publishing and insights retrieval for Threads. Careful management of API call frequency will be necessary to avoid disruptions. User insights are noted as not being guaranteed to work before June 1, 2024.28

D. Sharing & Social Plugins

Overview of Analytics: Meta has historically provided analytics for how users interact with Social Plugins (such as the Like button, Share button, and Comments Box) embedded on external websites, as well as for content shared from websites to Facebook. This data offers visibility into off-platform engagement that drives traffic and interaction back to Meta platforms and the source website.31 The primary mechanism for accessing such data has been through domain-level insights via the Graph API, evolving from older systems like FQL.

Metrics (Primarily from historical "Insights for Websites" documentation):

Like Button Analytics: Metrics included the number of times Like buttons were viewed on an external site, the number of clicks on those Like buttons, the number of times stories generated by those Likes were seen on Facebook, and the number of clicks on those Facebook stories that led back to the external website.32

Comments Box Analytics: Similar to the Like button, metrics covered the number of times the Comments Box was viewed on an external site, the number of comments left via the plugin, the number of times stories generated by those comments were seen on Facebook, and the number of clicks on those Facebook stories leading to the site's content.32

Organic Sharing: Analytics also captured traffic generated from links to an external site that were shared directly by users on Facebook (e.g., copy-pasting a URL into a status update or using older "Share" functionalities).32

Dimensions (Primarily from historical "Insights for Websites" documentation):

Demographics: A significant dimension was the availability of demographic data for interactions occurring both on the external site (via plugins) and on Facebook related to shared content. This included breakdowns by gender, age range, country, and language. This data was provided on an aggregated, per-interaction basis to protect personally identifiable information.32

API Access Details:

Endpoints: Historically, website and domain-level insights were accessible through the Graph API by querying a domain object (e.g., /{DOMAIN_ID}/insights) or via the now-deprecated FQL insights table.32 The current Graph API equivalent for domain-level insights would need to be verified, but the read_insights permission is generally associated with such data. The URL node in the Graph API can provide information about a URL, including share counts, but comprehensive plugin interaction metrics might require different endpoints or specific feature access.

Authentication: Accessing domain-level insights typically requires an App access token or a User access token belonging to an administrator of the domain (verified ownership in Meta systems).

Permissions: The read_insights permission would be fundamental for accessing any analytics related to a verified domain.33

Versioning/Rate Limits: These would adhere to general Graph API principles.

The analytics for social plugins embedded on external websites are valuable for understanding the bridge between off-Meta properties and the Facebook ecosystem. They reveal how these plugins drive engagement and referral traffic. The provision of demographic data for these off-platform interactions offers a powerful tool for content and audience strategy optimization. However, it is important to note that some of the referenced documentation 32 is older and mentions FQL, which is deprecated. Therefore, developers must identify the current Graph API endpoints and methods for retrieving domain-level and plugin-specific analytics. While direct plugin interaction metrics might be less prominent in newer documentation, general URL share insights and referral traffic data (potentially through Page Insights if traffic sources are tracked) remain relevant. The Meta Content Library also provides data on public content shares, which can include links to external domains.34

E. Facebook Video API (including Live Video & Stories)

Overview of Video Insights: Meta provides comprehensive analytics for various video formats across its platform. Insights for on-demand videos, Reels published to Facebook Pages, and Ad Breaks are primarily accessed via the Video Insights endpoint (/{video_id}/video_insights).36 Insights for Facebook Page Stories are typically handled as a type of Page Post insight.13 Live Video analytics have distinct characteristics, with detailed VOD metrics available post-broadcast and specific functionalities for real-time elements like polls.39

Video-On-Demand (VOD) & Reels Metrics:

A wide array of metrics is available, including total_video_views (total 3-second views, with variants for unique views, autoplayed, clicked-to-play, organic, and paid distribution), total_video_complete_views (views to 97%), total_video_10s_views (10-second views), total_video_avg_time_watched, total_video_view_total_time, and total_video_retention_graph (showing viewership drop-off).36

Reels, when treated as videos on a Page, share many of these metrics. Specific Reels metrics like blue_reels_play_count (initial plays), fb_reels_replay_count (replays), post_impressions_unique (unique people who saw the Reel), and post_video_avg_time_watched (for Reels) are also documented.37

Live Video Insights:

Post-Broadcast (VOD) Metrics: Once a live broadcast concludes, it becomes a VOD, and standard video insights become applicable. Metrics such as total_video_views_live (3-second views during the live broadcast) and total_video_view_total_time_live (total view time during live broadcast) provide performance data from the live session.37

Poll Engagement: Polls can be created and managed during a live broadcast using the /{live-video-id}/polls edge, which creates VideoPoll objects.39 Each VideoPoll has a question, status (e.g., voting_open, closed), and an edge poll_options leading to VideoPollOption nodes.40 While the VideoPollOption reference 41 does not explicitly list fields for vote counts per option or total voters, this is the logical location for such engagement data. Developers would need to inspect the fields of the VideoPollOption node or related edges to confirm the availability of specific vote analytics.

Concurrent Viewers: The metric post_video_live_current_viewers is listed under Page Video Post insights, suggesting it may be available for live videos associated with a Page to track real-time viewership.14

Facebook Page Stories Insights:

Page Stories are typically treated as a type of Page Post for insights purposes. Metrics available for Page Posts, such as post_impressions, post_reach, post_story_adds (if applicable via post_activity_by_action_type with relevant story type dimensions), and engagement metrics (reactions, replies, taps forward/back for story formats) would apply.13 The Stories Insights Reference is mentioned in 38, which should be consulted for specific Story metrics.

Ad Breaks Metrics:

For videos monetized with Ad Breaks, specific metrics include total_video_ad_break_ad_cpm (cost per mille for ads), total_video_ad_break_ad_impressions (impressions of ads within breaks), and total_video_ad_break_earnings (estimated earnings from ad breaks).37

Dimensions:

The primary dimension for querying video insights is metric, allowing a comma-separated list of specific metrics. The period parameter (e.g., day, week, days_28, month, lifetime, total_over_range) defines the aggregation window.36

since and until parameters can be used for custom date ranges (data available for the past 2 years).37

Some video metrics support breakdowns by distribution type (e.g., page_owned, shared), country, and audience demographics (age, gender).37

API Access Details:

Versioning: Video Insights follow general Graph API versioning (e.g., v22.0 is referenced in examples 36).

Authentication: A Page access token is required, requested from a user who can perform the ANALYZE task on the Page where the video resides.36

Permissions: Core permissions include pages_read_engagement and read_insights. For creating or managing Live Video Polls, additional permissions like publish_video (for User live videos) or pages_manage_posts (for Page live videos) are needed.36

Rate Limits: General Graph API rate limits apply. Page-related video insights would likely fall under the Business Use Case rate limits for Pages.2

Facebook's video analytics are extensive, covering various formats from standard VODs and Reels to the specifics of Live Video and monetization through Ad Breaks. A key consideration for developers is how these different video types are handled for reporting; Reels often share metrics with general videos but may have unique ones, Live Video insights are primarily available as VOD metrics after the broadcast, with poll data being a distinct entity requiring separate queries. The fact that Page Story insights are integrated within the Page Post insights framework is an important structural detail for data retrieval strategies. The absence of explicitly detailed vote count fields for VideoPollOption in the provided snippets 41 means developers should consult the most current, complete API reference for that node to confirm how poll engagement is quantified.

A. WhatsApp Business Platform API

Overview of WhatsApp Analytics: The WhatsApp Business Platform offers analytics primarily through the WhatsApp Business Management API, covering conversation metrics, template performance, and cost breakdowns. The Cloud API itself provides access to more fundamental metrics like message send/delivery status, and specific features like Flows have their own metrics API.16

Account Metrics (Cloud API):

The Cloud API allows users to see the number of messages sent and delivered, among other metrics.16 Detailed specifications for these metrics would be found in the "Get Account Metrics" guide 16, though access to this specific guide 46 was not available in the provided research materials.

Conversation Analytics (Business Management API - /{WABA_ID}/conversation_analytics):

This endpoint provides insights into conversation volumes and associated costs.

Metrics: COST (approximate charges for conversations, though this may not be available for businesses billed through a Solution Partner post-July 1, 2023) and CONVERSATION (count of conversations).45

Dimensions/Filters: granularity (HALF_HOUR, DAILY, MONTHLY), start and end timestamps, phone_numbers (to filter by specific business phone numbers), metric_types (to select COST or CONVERSATION), conversation_categories (AUTHENTICATION, MARKETING, SERVICE, UTILITY), conversation_types (FREE_ENTRY_POINT, FREE_TIER, REGULAR), conversation_directions (BUSINESS_INITIATED, USER_INITIATED), and dimensions for breakdown (e.g., CONVERSATION_CATEGORY, COUNTRY, PHONE).45

Template Analytics (Business Management API - /{WABA_ID}/template_analytics):

This endpoint tracks the performance of specific message templates.

Metrics: SENT, DELIVERED, READ, CLICKED (for URL or Quick Reply buttons in MARKETING or UTILITY templates), and COST (approximate charges, with same Solution Partner billing caveat as above).45

Dimensions/Filters: granularity (DAILY), start and end timestamps (corrected to 0:00 UTC), template_ids (array of up to 10 template IDs), metric_types, and product_type (CLOUD_API or MARKETING_MESSAGES_LITE_API).45

Template analytics must be enabled on the WABA, and button click tracking can be opted out per template.45

Pricing/Cost Analytics (Business Management API - /{WABA_ID}/pricing_analytics):

Provides detailed breakdowns of messaging costs.

Metrics: COST (approximate charges), VOLUME (number of messages delivered).45

Dimensions/Filters: granularity (DAY, HALF_HOUR, MONTH), start and end timestamps, country_codes, phone_numbers, pricing_categories (e.g., AUTHENTICATION_INTERNATIONAL, UTILITY), pricing_types (e.g., FREE_CUSTOMER_SERVICE, REGULAR).45

Flow Metrics API (/{Flow-ID}?fields=metric...):

This API tracks the performance of the endpoint used by a WhatsApp Flow, not user interactions within the Flow itself.

Metrics: ENDPOINT_REQUEST_COUNT, ENDPOINT_REQUEST_ERROR (broken down by error types like timeout_error, unexpected_http_status_code), ENDPOINT_REQUEST_ERROR_RATE, ENDPOINT_REQUEST_LATENCY_SECONDS_CEIL (distribution of request latencies), ENDPOINT_AVAILABILITY.44

Dimensions/Filters: granularity (DAY, HOUR, LIFETIME), since and until timestamps. A minimum of 250 requests within a flow is required for data to be returned.44

API Access Details:

Versioning: API examples reference versions like v16.0 44 or imply current Graph API versions. The WhatsApp Business Management API and Cloud API generally align with Graph API versioning.

Authentication: Requires an access token (User or System User). Key permissions include whatsapp_business_management (for managing WABA assets and accessing analytics via Business Management API) and whatsapp_business_messaging (for sending/receiving messages via Cloud API).16

Rate Limits: The WhatsApp Cloud API is subject to Business Use Case Rate Limits.16 Specific rate limits for the Business Management API analytics endpoints are not detailed in the provided snippets but would fall under general WABA management rate limits.

WhatsApp analytics offer a multi-layered view, from basic message delivery status via the Cloud API to granular cost, conversation, and template performance insights through the Business Management API. The newer Flow Metrics API addresses the operational health of interactive flow endpoints. Developers should note the distinction in data availability for COST metrics depending on whether the business is billed directly by Meta or through a Solution Partner. The requirement to enable template analytics on the WABA is an important setup step.

B. Messenger Platform API

Overview of Messaging Insights API: The Messenger Platform provides insights into conversations and messages, primarily through an API that mirrors functionality found in a Facebook Page's Insights tab. These analytics are typically accessed by querying the /{page-id}/insights endpoint with Messenger-specific metrics.48

Metrics:

The Messaging Insights API offers several metrics, many of which were noted as "in development" in the available documentation.48 These include:

recurring_notification_tokens: Count of subscriptions to marketing messages, factoring in unsubscribes.

page_messages_engagement: Number of times users tapped a call-to-action button in Marketing Messages.

page_messages_sent: Number of Marketing Messages sent by the Page.

page_messages_read_ratio: Ratio of read messages to sent messages (for Marketing Messages; may not capture all reads if receipts are off).

page_messages_order_count: Number of orders created within messaging conversations or associated third-party apps.

page_messages_paid_order_earnings: Approximate earnings from orders via messaging.

page_messages_with_business_outcomes: Number of messaging connections that resulted in at least one order.

page_messages_blocked_conversations_unique: Number of unique conversations blocked by users.

page_messages_new_conversations_unique: Number of new messaging conversations with individuals who had not previously messaged the business.

page_messages_reported_conversations_unique: Number of unique conversations reported by users (e.g., for spam).

page_messages_total_messaging_connections: Total number of people the business can message (excluding blocked/reported users, data since Oct 2016).

Dimensions:

The primary way to segment these metrics is using the breakdowns parameter. Supported breakdown values include messaging_channel (allowing differentiation between Messenger and Instagram if Instagram Direct is managed via the Messenger Platform), recurring_notifications_topic, and recurring_notifications_frequency.48

Standard since and until parameters are used to define the time range for the query.48

API Access Details:

Versioning: Example requests in the documentation use v22.0, indicating alignment with general Graph API versioning.48

Authentication: A Page access token is required to query these insights, as they are associated with a specific Facebook Page.48

Permissions: The read_insights permission is necessary to access the Messaging Insights API endpoint.48

Rate Limits: While not explicitly detailed for Messaging Insights in the provided snippets, these calls would likely be subject to the same Business Use Case Rate Limits as other Page Insights queries when using a Page access token.2

The insights available for the Messenger Platform appear to focus significantly on the performance of marketing messages and the outcomes of conversations, particularly concerning e-commerce activities like orders. The "in development" status for many of the listed metrics 48 is a critical point; developers should verify the current availability and stability of these metrics directly from the latest Meta documentation before relying on them for production reporting. The messaging_channel breakdown is particularly noteworthy as it suggests a unified way to potentially analyze messaging performance across both Messenger and Instagram Direct if managed through the Messenger Platform.

A. Facebook App Ads (via Marketing API / Ads Insights API)

Overview: Performance tracking for Facebook App Ads is facilitated through the Marketing API's Ads Insights API. This API provides a comprehensive suite of metrics and dimensions to analyze the effectiveness of campaigns, ad sets, and individual ads designed to promote mobile applications.12 The data allows advertisers to measure user acquisition, engagement, and return on ad spend (ROAS) specifically for app-focused objectives.

Metrics:

Standard Ad Performance Metrics: Common advertising metrics are available, such as impressions (number of times ads were on screen), clicks (on ads), spend (estimated total cost), reach (unique people who saw ads), frequency (average times each person saw an ad), cpc (cost per click), cpm (cost per mille/1000 impressions), and ctr (click-through rate).12

Conversion-Focused Metrics: Metrics crucial for app campaigns include actions (which can be broken down by specific action types like mobile_app_install, app_custom_event for in-app actions such as purchases or level completions), action_values (the value associated with these actions), conversions (a general count of conversion events), cost_per_action_type, and cost_per_conversion.12

App-Specific Metrics: The API provides metrics tailored to app advertising, such as mobile_app_purchase_roas (return on ad spend from mobile app purchases). For postback data from mobile measurement partners or Meta's SDK, fields like redownload (indicating if a user reinstalled the app) and fidelity_type (distinguishing StoreKit-rendered ad interactions from view-through attributions for SKAdNetwork) can be available within detailed postback fields like total_postbacks_detailed_v4.12

SKAdNetwork Metrics: For iOS app campaigns, metrics related to Apple's SKAdNetwork are increasingly important. These include skan_campaign_id, skan_conversion_id (the conversion value reported by SKAdNetwork), skan_version (the version of SKAdNetwork used), coarse_conversion_value (providing directional post-install quality insights for SKAdNetwork 4.0+), and hsid (Hierarchical Source ID for SKAdNetwork 4.0+).12 These are typically found within detailed postback data.

Dimensions (Breakdowns):

Standard Demographics: Performance can be segmented by age, gender, country, and region.12

Placement: Breakdowns by publisher_platform (e.g., Facebook, Instagram, Audience Network), platform_position (e.g., feed, stories), and impression_device (e.g., mobile, desktop) allow for analysis of where ads perform best.12

App-Specific: The app_id dimension can be used if reporting across multiple apps.

Time-Based: Data can be aggregated by hourly_stats_aggregated_by_advertiser_time_zone or by date_start and date_stop for daily/custom range reporting.12

Attribution: The action_attribution_windows dimension is critical, allowing data to be viewed based on different attribution models (e.g., 1d_click for 1-day click-through, 7d_click for 7-day click-through, 1d_view for 1-day view-through).15

API Access Details:

Endpoints: Insights are typically queried from edges on ad objects: act_{AD_ACCOUNT_ID}/insights (ad account level), /{CAMPAIGN_ID}/insights (campaign level), /{ADSET_ID}/insights (ad set level), or /{AD_ID}/insights (ad level).12 The level parameter (e.g., level=ad) can be used to specify the aggregation level when querying a parent object.15

Versioning: App Ad insights follow the Marketing API versioning scheme (e.g., v22.0 is referenced in documentation).12

Authentication: A User access token with the appropriate permissions is required.15

Permissions: The ads_read permission is necessary for retrieving Ads Insights data. If the integration also involves managing ads, ads_management would be required.12

Rate Limits: Calls are subject to the Ads Insights Business Use Case (BUC) Rate Limits. These limits are influenced by factors such as the app's access tier (Standard or Advanced for Ads Management Standard Access) and the number of active ads in the account.2

Reporting for Facebook App Ads leverages the general Ads Insights API, with a specific focus on app-related conversion events (installs, in-app actions) and, particularly for iOS, SKAdNetwork-derived metrics. Understanding how Meta reports SKAdNetwork data alongside its own modeled conversion data is vital for a complete picture of iOS app campaign performance. The action_attribution_windows dimension is fundamental for interpreting how different user interactions are credited with leading to app installs or other conversions.

B. Automotive Ads (via Marketing API / Ads Insights API)

Overview: Facebook Automotive Inventory Ads are a specialized solution within the Marketing API designed for car dealerships and manufacturers to promote their vehicle inventory. Performance reporting for these ads also utilizes the general Ads Insights API, but the key to effective automotive reporting lies in leveraging the rich data from the automotive catalog feed as dimensions to segment performance metrics.12

Metrics:

Standard ad performance metrics available through the Ads Insights API apply. These include impressions, clicks, spend, reach, frequency, conversions (e.g., leads, website visits to vehicle detail pages), cost_per_action_type, and ROAS-related metrics.12

While not explicitly detailed as distinct "automotive metrics" in the Ads Insights API reference, metrics like catalog_segment_actions and catalog_segment_value 12 could be relevant if automotive inventory is structured into catalog segments. The primary value comes from breaking down standard metrics by vehicle attributes.

Dimensions (Breakdowns):

Standard Demographics and Placements: Breakdowns by age, gender, country, publisher_platform, platform_position, etc., are available as with any ad campaign.12

Catalog-Derived Dimensions: This is where automotive ad reporting becomes specialized. The Ads Insights API supports breakdowns by various product attributes. For automotive ads, these product attributes are populated from the fields in the automotive catalog feed. Essential fields from the automotive catalog that can become dimensions for reporting include vehicle_id (often the VIN), make, model, year, body_style, trim, exterior_color, state_of_vehicle (new, used, CPO), drivetrain, fuel_type, price, mileage.value, dealer_id, dealer_name, and custom labels (custom_label_0 through custom_label_4 for vehicles, and custom_number_0 through custom_number_4 for vehicles).54 The Ads Insights API provides generic product breakdown fields like product_id (which would map to vehicle_id or vin), product_name (mapping to title), product_brand (mapping to make), product_category (potentially body_style or vehicle_type), and product_custom_label_0 etc..12 The successful mapping of these catalog fields to the Ads Insights product dimensions is crucial for granular reporting.

Destination Type: For Automotive Inventory Ads with an on-Facebook destination (e.g., directing users to a vehicle listing on Facebook Marketplace), the destination_type in the ad set would be FACEBOOK.54 This can also be a reporting dimension.

API Access Details:

Endpoints: Reporting data is accessed via the standard Ads Insights API endpoints: act_{AD_ACCOUNT_ID}/insights, /{CAMPAIGN_ID}/insights, /{ADSET_ID}/insights, /{AD_ID}/insights.12

Versioning: Follows the general Marketing API versioning policies.12

Authentication: Requires a User access token.15

Permissions: The ads_read permission is necessary for fetching insights data.12

Rate Limits: Subject to the Ads Insights Business Use Case (BUC) Rate Limits, which are influenced by factors like app access tier and the number of active ads.2

The effectiveness of automotive ad reporting hinges on the ability to segment general ad performance metrics by the specific attributes of the vehicles being advertised (e.g., make, model, VIN, condition, dealer). This requires a robust automotive catalog feed with accurately populated fields, as detailed in the Automotive Inventory Ads supported fields documentation 54, and then leveraging the product-level breakdown dimensions available in the Ads Insights API.12 For example, an advertiser would want to see not just total clicks, but clicks for "2023 Ford Explorer" or clicks for vehicles from a specific dealer_id. This detailed segmentation allows for optimization based on which specific inventory items or categories are performing best.

Summary of Key Findings:

The Meta API suite offers extensive reporting capabilities across its diverse services, with the Graph API serving as a foundational framework for many interactions. A common pattern is the availability of object-specific insights, such as distinguishing between Page-level and Post-level analytics for Facebook Pages, or Account-level versus Media-level insights for Instagram.

Successfully integrating these APIs for reporting necessitates a deep understanding of and adherence to Meta's protocols for API versioning, robust authentication using appropriate access tokens and permissions, and diligent management of rate limits to ensure application stability and continuous data flow.

Recommendations for Developers:

Unified Authentication Strategy: Given the variety of access tokens (User, Page, App, System User) and their different lifespans and use cases, development teams should implement a centralized and secure strategy for obtaining, storing, and refreshing these tokens. For backend reporting systems requiring continuous access, long-lived Page access tokens or System User access tokens are generally preferred.4

Proactive Version Management: Meta's APIs evolve with quarterly version releases. Integrations should explicitly specify API versions in calls to avoid unexpected behavior from default versioning. A process should be established to monitor Meta's API changelogs and regularly review and update the integration to align with new versions, manage deprecations, and leverage new features.3

Dynamic Rate Limit Handling: Reporting integrations can be call-intensive. Implement adaptive data fetching logic that monitors usage via the X-App-Usage and X-Business-Use-Case-Usage headers. This allows the application to dynamically adjust call frequency, pause, and resume based on real-time limit status, preventing throttling and service disruptions.2

Granular Data Fetching: Utilize Graph API features like field expansion to request only the specific data fields required for reporting. For endpoints that support breakdowns or filtering (e.g., by date range, metric type, or dimension), leverage these to retrieve targeted datasets. This optimizes API call efficiency, reduces data transfer, and minimizes client-side processing load.7

Comprehensive Error Logging: Implement thorough logging of all API requests and responses. Capturing the full error object, including the fbtrace_id, is crucial for diagnosing issues and for effective communication with Meta Developer Support if needed.5

Modular Design for Integration: The metrics, dimensions, and access patterns can vary significantly between different Meta APIs (e.g., Pages API vs. Marketing API vs. WhatsApp Business API). Designing the reporting integration in a modular fashion will make it easier to manage these differences, update individual components, and extend functionality to new Meta services in the future.

Common Pitfalls to Avoid:

Insecure Token Storage: Never hardcode access tokens or, especially, App Secrets directly into client-side applications or version control. This exposes sensitive credentials and can lead to account compromise.4

Ignoring Pagination: Many API endpoints that return lists of data use cursor-based pagination. Failing to implement logic to follow next page links will result in incomplete data sets.15

Neglecting Token Expiration and Revocation: Access tokens can expire or be revoked by users. Reporting systems must gracefully handle these scenarios, typically by attempting to refresh the token or prompting for re-authentication, to avoid data collection interruptions.5

Overlooking Data Retention Policies: Different types of insights data may have different retention periods (e.g., Page Insights generally available for 2 years 13, some Instagram user metrics for 90 days 22). Reporting systems should be aware of these limits to manage historical data expectations.

Misinterpreting Aggregated Metrics: Be cautious when summing "unique" metrics across different dimensions or time periods, as these are often de-duplicated at their specific aggregation level and may not be additive. Similarly, understand the distinction between paid, organic, and viral reach/impressions to avoid misrepresenting performance.13

Emphasis on Ongoing Monitoring and Adaptation:

The Meta API ecosystem is dynamic. New features are introduced, existing ones are updated, and occasionally, functionalities are deprecated. Developers must treat the official Meta Developer Documentation, API Changelogs, and Developer Blogs/Forums as essential, ongoing resources to stay informed of these changes.1

Regularly testing the integration, especially in conjunction with new API version releases or significant platform updates announced by Meta, is critical to ensure continued functionality and data accuracy for the reporting platform.