Analytics
Read impressions, likes, replies, reposts and bookmarks for X posts, how often they refresh and what they cost.
Read metrics for an X post published through Onepostly or synced from outside it. The connection needs the tweet.read permission, which is granted when you connect.
Metrics
| Field | X metric | Notes |
|---|---|---|
impressions | Impressions | |
reach | None | Always null |
plays | Impressions | Same value as impressions |
likes | Likes | |
comments | Replies | |
shares | Reposts plus quotes | |
saves | Bookmarks | |
engagement | Likes, replies, reposts, quotes and bookmarks | Sum of likes, comments, shares and saves |
X returns its detailed (organic) counts only to the post's author and only for 30 days after posting. After that, the fields hold X's public counts. A value X does not return stays null.
Read Post Analytics
Pass the Onepostly post id, or the X post id with accountId for posts published outside Onepostly (see Targeting Posts and Outside Posts).
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": "x",
"externalPostId": "17895695668004550",
"status": "ready",
"metrics": {
"impressions": 1234,
"reach": null,
"likes": 123,
"comments": 12,
"shares": 4,
"saves": 2,
"plays": 456,
"engagement": 0.14
},
"fetchedAt": "2026-08-25T10:00:00.000Z",
"expiresAt": "2026-09-01T10:00:00.000Z",
"error": null,
"externalUrl": "https://x.com/you/status/17895695668004550"
}
]
}
}X metrics are read from X when you call this endpoint, at most once per post per UTC day. The first read of a day is charged (Billing); later reads that day return the same numbers at no charge. A read that returns no metrics is not charged.
Analytics Status
Status values are described in Analytics Status. For X:
- A post that was deleted on X, or is no longer visible to the account, reports
unavailablewithPOST_NOT_FOUND. - The daily timeline is not available for X; a timeline request for X posts only fails with
TIMELINE_UNSUPPORTED. Read the analytics endpoint each day instead.
Errors
| Code | Cause | Fix |
|---|---|---|
NOT_PUBLISHED | The Onepostly post has no live X post yet | Read analytics after the destination is published |
POST_NOT_FOUND | The post was deleted on X or is not visible to the account | Check that the post still exists on X |
ANALYTICS_PERMISSION | X refused access to the account's metrics | Reconnect the account |
ANALYTICS_FAILED | X rejected the metrics request | Read the error message, then read again later |
TIMELINE_UNSUPPORTED | A daily timeline was requested for X posts | Use GET /v1/analytics instead |
INSUFFICIENT_WALLET | The wallet balance is too low | Top up in Dashboard → Settings → Billing, then read again |
RATE_LIMITED | X throttled the account | Read again later |
X_OUT_OF_CREDITS | X is temporarily not accepting this request; the wallet is not charged | Read again later; contact support if it continues |
PLATFORM_UNAVAILABLE | X had a temporary failure | Read again later |