Analytics
Read Facebook post metrics, Page insights, Page stats, and Page recommendations.
Read normalized metrics for Facebook posts and live numbers for the Page itself. Post metrics and Page insights need the read_insights permission, which Onepostly requests when you connect.
Metrics
| Field | Facebook metric | Notes |
|---|---|---|
impressions | post_media_view | |
reach | post_total_media_view_unique | |
plays | post_video_views | video and stories posts only; null for other posts |
likes | Like count | Falls back to the total reaction count |
comments | Comment count | |
shares | Share count | |
saves | None | Always null; Facebook does not report saves |
engagement | post_engaged_users | A count, not a rate. Falls back to post_clicks, then to likes + comments + shares |
A metric Facebook does not report for a post stays null.
Read Post Analytics
Pass the Onepostly post id, or a Facebook post id with accountId. See Targeting Posts for the selector and for posts published outside Onepostly. For day-by-day values, see Daily timeline.
import { Configuration, AnalyticsApi } from "@onepostly/sdk";
const analyticsApi = new AnalyticsApi(
new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);
const response = await analyticsApi.getAnalytics({
post: "1699f415-7fb6-43f4-9d2a-c447491f32a8",
metrics: "views,reach,profile_views",
period: "day",
});
console.log(response);{
"analytics": {
"post": "1699f415-7fb6-43f4-9d2a-c447491f32a8",
"status": "ready",
"fetchedAt": "2026-08-25T10:00:00.000Z",
"subjects": [
{
"scope": "destination",
"subjectId": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
"accountId": "a1b2c3d4-e5f6-4a7b-8c9d-e0f1a2b3c4d5",
"platform": "facebook",
"externalPostId": "17895695668004550",
"status": "ready",
"metrics": {
"impressions": 1234,
"reach": 987,
"likes": 123,
"comments": 12,
"shares": 4,
"saves": null,
"plays": 456,
"engagement": 0.14
},
"fetchedAt": "2026-08-25T10:00:00.000Z",
"expiresAt": "2026-09-01T10:00:00.000Z",
"error": null,
"externalUrl": "https://www.facebook.com/page/posts/17895695668004550"
}
]
}
}Account Stats
Page Stats
GET /v1/connections/{id}/stats returns live Page numbers: followerCount is the Page's followers and likesCount is its Page likes. followingCount and videoCount are always null.
Add include=reviews to also return Page recommendations in reviews (limit 1 to 50, default 20). Each review has rating, text, createdAt, reviewerId, and reviewerName, any of which can be null. If Facebook does not return them, reviews is left out of the response.
import { Configuration, ConnectionsApi } from "@onepostly/sdk";
const connectionsApi = new ConnectionsApi(
new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);
const response = await connectionsApi.getConnectionStats({
id: "YOUR_FACEBOOK_ACCOUNT_ID",
include: "reviews",
limit: 20,
});
console.log(response);{
"accountId": "YOUR_FACEBOOK_ACCOUNT_ID",
"platform": "facebook",
"status": "ready",
"stats": {
"followerCount": 5230,
"followingCount": null,
"likesCount": 4980,
"videoCount": null
},
"reviews": {
"reviews": [
{
"id": "1029384756102938",
"rating": null,
"text": "Best sourdough in town.",
"createdAt": "2027-03-14T18:20:00+0000",
"reviewerId": "8261937452018734",
"reviewerName": "Ana Silva"
}
],
"cursor": null
},
"fetchedAt": "2027-03-15T09:00:00.000Z"
}Page Insights
Call GET /v1/analytics with only accountId to read live Facebook Page Insights. Always pass metrics with current Facebook Page Insights metric names, such as page_media_view and page_follows; a request without metrics can fail with ANALYTICS_FAILED.
| Parameter | Value |
|---|---|
metrics | Comma-separated Facebook Page Insights metric names, up to 20 |
period | day (default), week, days_28, or lifetime |
since, until | Unix timestamps in seconds |
Each row in rows is one metric as Facebook reports it. demographics is always empty for Facebook.
import { Configuration, AnalyticsApi } from "@onepostly/sdk";
const analyticsApi = new AnalyticsApi(
new Configuration({ apiKey: process.env.ONEPOSTLY_API_KEY })
);
const response = await analyticsApi.getAnalytics({
post: "1699f415-7fb6-43f4-9d2a-c447491f32a8",
accountId: "YOUR_FACEBOOK_ACCOUNT_ID",
metrics: "page_media_view",
period: "day",
});
console.log(response);{
"accountId": "YOUR_FACEBOOK_ACCOUNT_ID",
"platform": "facebook",
"rows": [
{
"name": "page_media_view",
"period": "day",
"values": [
{
"value": 1840,
"end_time": "2027-03-14T07:00:00+0000"
},
{
"value": 2115,
"end_time": "2027-03-15T07:00:00+0000"
}
]
}
],
"demographics": {}
}Analytics Status
Status values are described in Analytics status. On Facebook:
- A post read right after publishing usually returns
ANALYTICS_PENDINGwhile Facebook prepares its metrics. Read again later. - A post deleted on Facebook returns
POST_NOT_FOUND. This status is final. - Reels report no
plays.
Errors
Post reads return these codes in each subject's error. Page Insights and Page stats return them on the request.
| Code | Cause | Fix |
|---|---|---|
NOT_PUBLISHED | The Facebook destination is not published yet | Read again after it is published |
ANALYTICS_PENDING | Facebook has no metrics for the post yet | Read again later |
POST_NOT_FOUND | The post no longer exists on Facebook | None; the status is final |
ANALYTICS_PERMISSION | Missing read_insights, or your Page role has no insights access | Reconnect with all permissions, or get insights access on the Page |
TOKEN_INVALID | The Page connection expired or was revoked | Reconnect the Page |
RATE_LIMITED | Facebook throttled the read | Read again later |
ANALYTICS_FAILED | Facebook rejected the read, for example an unknown metric name in metrics | Check the metric names, then read again |
STATS_FAILED | Facebook did not return the Page stats | Read again later |