Analytics
Views, likes, comments and shares for YouTube videos, and how YouTube metrics map to Onepostly fields.
Read lifetime metrics for a published YouTube video. Shares need the yt-analytics.readonly permission; the other metrics work without it.
Metrics
| Field | YouTube metric | Notes |
|---|---|---|
impressions | Views | Same value as plays |
reach | Not supported | Always null |
plays | Views | |
likes | Likes | |
comments | Comments | |
shares | Shares | null without yt-analytics.readonly. Can trail the other metrics by a few days |
saves | Not supported | Always null |
engagement | Likes + comments + shares | Sum of the values present |
Read Post Analytics
Pass the Onepostly post id, or the YouTube video id plus accountId (see Targeting Posts). Videos uploaded outside Onepostly work after you sync them (see Outside Posts). 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": "youtube",
"externalPostId": "17895695668004550",
"status": "ready",
"metrics": {
"impressions": 1234,
"reach": null,
"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.youtube.com/watch?v=17895695668004550"
}
]
}
}Analytics Status
Status values are described in Analytics Status. On YouTube:
- A new video reads
pendinguntil YouTube reports its first metrics. - A
privatevideo can staypendingwhen the connection cannot see it. Reconnect with all permissions approved. - A video deleted or removed on YouTube reads
unavailablewithVIDEO_NOT_FOUND. This status is final.
Errors
These codes appear in the error object of an analytics result.
| Code | Cause | Fix |
|---|---|---|
NOT_PUBLISHED | The destination is not published | Wait until the destination is published |
ANALYTICS_PENDING | YouTube has not reported metrics for the video yet | Read again later |
ANALYTICS_PERMISSION | The connection lacks a required permission | Reconnect the account and approve all permissions |
VIDEO_NOT_FOUND | The video no longer exists on YouTube | Stop reading analytics for this video |
QUOTA_EXCEEDED | YouTube is at capacity for this action | Read again in a few hours |
RATE_LIMITED | YouTube throttled the request | Read again in a few minutes |
ANALYTICS_FAILED | YouTube returned an error for the video | Read again later; contact support if it persists |