Skip to content

Facebook Analytics API

This Facebook Analytics API lets a product, reporting workflow, automation, or AI system fetch Facebook Page post engagement through a single endpoint.

Recent Page Posts request
curl -X GET "{{API_BASE_URL}}/v1/analytics?source=platform&platform=facebook&accountId=acc_fb_page_456&limit=10&page=1" \
 -H "x-access-key: your-api-key"
Illustrative request
Example line 1

curl -X GET "{{API_BASE_URL}}/v1/analytics?source=platform&platform=facebook&accountId=acc_fb_page_456&limi…

Illustrative request
Example line 2

-H "x-access-key: your-api-key"

For eligible Page posts it supplies likes, comments, and shares, can fetch posts straight from a connected Page, and supports date-range filtering plus performance-based ordering. Authentication and the separate token held for each Page are handled by the integration, so an application deals with connected Pages instead of managing Page tokens itself.

What the Facebook Analytics API retrieves and how to integrate it step by step

This API is intended for developers who need Facebook Page engagement inside an existing product or reporting process. Pages are connected once, after which eligible posts can be queried through a single analytics endpoint instead of maintaining a separate connection for every Page. The data returned consists of likes, comments, and shares, giving dashboards and reports a consistent group of engagement signals to show, compare, and export.

Integration begins with identifying the Page to report on. Each connected Facebook Page carries its own integration ID, passed as accountId. That identifier keeps reporting for separate Pages apart: changing accountId changes which Page's posts come back, while the endpoint and response shape stay the same. Supplying an accountId for the wrong Page will return that Page's data or nothing useful for the intended Page, so keep the accountId stored next to the Page it represents and confirm it before running recurring reports.

Content can be selected in two principal ways. Setting source=platform fetches eligible posts directly from the connected Facebook Page. The workflow-published source value listed in the request parameters table fetches Facebook content delivered through the unified publishing workflow, and a stored postId can narrow that to one delivered post. The choice depends on provenance: source=platform answers what the Page itself published, while the workflow-published value answers what the publishing workflow delivered. For one known post, postId is the selector; for a Page-level view, accountId is. Confusing the two identifiers is a frequent mistake, so confirm which identifier is available before calling the endpoint.

Date, ordering, and paging controls shape the query. Set fromDate and toDate to limit results to the period being reported, for example a campaign window or a monthly review. Apply sortBy together with order to arrange the Page posts that come back, and use page together with limit to step through a bigger set. Dashboards should treat paging as part of the design: request a fixed page size, follow the total and page values in the response, and continue until the whole set is covered. A report that silently displays only the first page usually reflects missing paging logic rather than an absence of further posts.

The response keeps a post-level summary apart from platform-specific detail. Each item in posts includes a source, a postId that can be null for platform-sourced posts, the post content, a publishedAt timestamp, an aggregated metrics object, and a platforms array holding the Facebook metrics. In the captured example, likes, comments, and shares carry values, while impressions, reach, saves, clicks, views, and engagementRate are null. Code should therefore check for null metrics explicitly and display a missing value as unavailable instead of zero, because null here means the metric was not supplied, not that engagement was zero. Adding nulls as zeros would understate performance and distort any engagement-rate calculation built on the data.

Several boundaries should shape the design. Only Facebook Pages are supported; personal profiles cannot be queried through the current Graph API workflow, so Page analytics should not be offered to users who connect a personal profile. Only likes, comments, and shares are exposed for eligible Facebook Page posts, so impressions, reach, clicks, or views should not be promised from this endpoint. OAuth, long-lived token exchange, and the per-Page token model are handled by the integration, which simplifies the application but means token lifecycle problems appear as integration issues rather than credentials the application can refresh itself. The same connected accounts can also support posting, scheduling, and comment management, making analytics a natural extension of an existing publishing workflow rather than a separate connection.

Integration checklist and failure checks

To integrate the endpoint, first confirm that the account being queried is a connected Facebook Page and record its accountId. Next, decide whether Page-sourced posts or workflow-published posts are needed, and select the matching source value. Then apply fromDate and toDate for the reporting period, choose sortBy and order for the ordering the interface needs, and set page and limit so the caller can walk the full result set. Finally, parse the posts array, read likes, comments, and shares from the metrics objects, and handle null values for any metric that is not populated. Verify each step by checking that the returned posts belong to the intended Page, that the date window matches the report, and that paging reaches the reported total before treating the integration as complete.

Add social media to your product in three steps

The integration follows a simple three-step sequence. First, connect the Facebook Page and obtain its accountId, which is the per-Page integration identifier used in every analytics request. Second, integrate the analytics endpoint by selecting the correct source, applying date, sort, and pagination parameters, and parsing likes, comments, and shares from the response. Third, support every connected Page through the same endpoint by storing one accountId per Page and querying each Page independently, rather than building a separate integration for each Page. This sequence keeps onboarding predictable: connection establishes identity, the endpoint call establishes data access, and per-Page accountId handling establishes multi-Page reporting.

Use Facebook analytics in any stack

The same analytics endpoint can be used from different kinds of systems. In a developer stack, typed SDKs and predictable REST calls let you integrate the endpoint into the application you already maintain, using the request and response formats shown in the examples. In no-code workflows, automation tools can trigger analytics queries and route likes, comments, and shares into sheets, dashboards, or notifications without custom code. For AI agents and MCP, an agent can call the same endpoint to retrieve Page performance on demand, provided it supplies the correct accountId or postId and respects the Pages-only boundary. The stack changes, but the contract does not: source, platform, accountId, date, sort, and pagination parameters remain the same.

Other supported platforms

Facebook is one of several networks available through the same unified approach. Other platform analytics pages cover Twitter/X, YouTube, Pinterest, LinkedIn, TikTok, and Instagram, each retrieving performance metrics for supported posts on that network. Starting with Facebook and then extending to other networks through the same API pattern lets a product offer consistent reporting without maintaining a separate integration per network. Each platform still has its own supported metrics and account types, so verify the boundary for each network before promising the same fields everywhere.

Additional social capabilities

Beyond analytics, the same connected accounts support additional social capabilities. A posting API publishes to every network through one endpoint. A scheduling API queues and delivers posts at a chosen time. A comments API reads, replies to, hides, and manages comments. A messaging API handles direct-message conversations. A comment to DM API can automatically message commenters by keyword, with an optional public reply. These capabilities share the connected-account model with analytics, so a product that already connects a Facebook Page for reporting can extend the same connection to publishing, scheduling, comments, messaging, and comment to DM workflows without asking users to connect the Page again.

GET /v1/analytics request parameters
ParameterExample valuePurpose
sourceplatformSelects the content source; source=platform retrieves posts directly from the connected Page, while source=postpeer retrieves workflow-published content.
platformfacebookSelects Facebook as the platform.
accountIdacc_fb_page_456Identifies the connected Facebook Page to query.
limit10Controls how many results are returned per page.
page1Selects which page of results to return.
postIdstored postIdIdentifies a specific published post when querying workflow-published content.
fromDatereporting startNarrows results to the start of the reporting period.
toDatereporting endNarrows results to the end of the reporting period.
sortBysupported sort fieldOrganizes returned Page posts by the selected field.
ordersupported orderSets the direction used with sortBy.

Parameter names, case, and example values are preserved exactly as captured. Requiredness and types beyond the captured example were not supplied and are not asserted here.

GET /v1/analytics response fields
FieldType in exampleMeaning
successbooleanIndicates whether the request succeeded.
totalnumberTotal number of matching posts.
pagenumberCurrent page of results.
limitnumberPage size used for the request.
postsarrayList of post analytics entries.
posts[].sourcestringSource of the post, such as platform.
posts[].postIdstring or nullStored post identifier; null for platform-sourced posts in the example.
posts[].contentstringPost content.
posts[].publishedAtstringPublication timestamp.
posts[].aggregatedobjectAggregated metrics across platforms.
posts[].aggregated.likesnumberLike count.
posts[].aggregated.commentsnumberComment count.
posts[].aggregated.sharesnumberShare count.
posts[].aggregated.impressionsnullNot populated in the captured Facebook example.
posts[].aggregated.reachnullNot populated in the captured Facebook example.
posts[].aggregated.savesnullNot populated in the captured Facebook example.
posts[].aggregated.clicksnullNot populated in the captured Facebook example.
posts[].aggregated.viewsnullNot populated in the captured Facebook example.
posts[].aggregated.engagementRatenullNot populated in the captured Facebook example.
posts[].platformsarrayPer-platform detail for the post.
posts[].platforms[].platformstringPlatform identifier, facebook in the example.
posts[].platforms[].platformPostIdstringIdentifier of the post on the platform.
posts[].platforms[].platformPostUrlstringURL of the post on the platform.
posts[].platforms[].metricsobjectFacebook-specific metrics for the post.

Field names and null values are preserved exactly as captured in the example response.

Choosing source, accountId, and postId
SituationWhat to checkExpected behavior
Posts directly from a connected Pagesource=platform with platform=facebook and the Page accountIdReturns supported Page posts with likes, comments, and shares.
Content published through the unified workflowsource=postpeerReturns Facebook content published through the workflow.
One specific published postStored postIdReturns analytics for that published post.
Multiple Facebook PagesOne accountId per connected PageEach Page is queried independently using its own accountId.
A defined reporting periodfromDate and toDateResults are focused on the requested period.
Ordered, paginated resultssortBy, order, page, and limitResults are organized and returned page by page.

Decision criteria derived from the captured source descriptions; no additional endpoint behavior is asserted.

Failure and edge-case matrix
Failure or edge caseCauseCheck
Metric shows as nullMetric not populated for Facebook in the responseTreat null as unavailable, not as zero.
Personal profile connectedOnly Facebook Pages are supportedDo not query personal profiles through this integration.
Wrong Page data returnedIncorrect or mismatched accountIdVerify the accountId belongs to the intended Page.
Report shows only some postsPagination not followedUse page and limit until the reported total is covered.
Single post not found in Page viewPost was workflow-published rather than Page-sourced, or vice versaConfirm whether source=platform or the workflow-published source applies, and use postId for a specific published post.

Checks are derived from the captured contract and stated limitations; no additional error contract was supplied.

Frequently asked questions

Which Facebook Page metrics can I retrieve?

For supported Page posts, the endpoint returns three populated counts: likes, comments, and shares. Fields such as impressions, reach, saves, clicks, views, and engagementRate appear as null in the captured Facebook example, so treat those as unavailable rather than zero.

Can I retrieve posts directly from a connected Facebook Page?

Yes. Set source=platform, set platform=facebook, and supply the connected Page's accountId. That combination returns supported posts belonging to that Page.

Can I retrieve analytics for Facebook posts published through the unified publishing workflow?

Yes. Use the workflow-published source value to list Facebook items delivered through the unified publishing workflow. When you already have the stored identifier for one delivered item, pass its postId to focus on that item alone. The exact source value is shown in the request parameters table.

Does Facebook Analytics work with personal profiles?

No. Support is limited to Facebook Pages. A personal profile cannot be queried through this integration under the current Graph API workflow.

Can I retrieve analytics for multiple Facebook Pages?

Yes. Every connected Page is assigned a separate integration identifier. Supplying that identifier as accountId scopes the query to one Page at a time, so several Pages can be reported independently.

Can I filter and sort Facebook Page analytics?

Yes. Apply fromDate and toDate to bound the reporting window. Then choose sortBy and order for ordering, and page plus limit to page through the matching set.

Do I need to manage Facebook OAuth and Page tokens myself?

No. The integration handles the OAuth flow, long-lived token exchange, and the per-Page token model for connected Facebook Pages, so your application does not manage those credentials directly.

Can I build a multi-Page Facebook reporting dashboard?

Yes. Query each Page with its own accountId, collect likes, comments, and shares, and assemble those results in your dashboard. That approach supports reporting grouped by client, brand, or business Page.

Recent Page Posts response
{
    "success": true,
    "total": 1,
    "page": 1,
    "limit": 10,
    "posts": [
      {
        "source": "platform",
        "postId": null,
        "content": "A short example update.",
        "publishedAt": "2026-08-28T14:22:00Z",
        "aggregated": {
          "impressions": null,
          "reach": null,
          "likes": 142,
          "comments": 18,
          "shares": 9,
          "saves": null,
          "clicks": null,
          "views": null,
          "engagementRate": null
        },
        "platforms": [
          {
            "platform": "facebook",
            "platformPostId": "123456789_987654321",
            "platformPostUrl": "https://www.facebook.com/yourpage/posts/987654321",
            "metrics": {
              "impressions": null,
              "reach": null,
              "likes": 142,
              "comments": 18,
              "shares": 9,
              "saves": null,
              "clicks": null,
              "views": null,
              "engagementRate": null
            }
          }
        ]
      }
    ]
}