Metrics, retention and CTR
Post metrics, and what YouTube and Instagram report about who watched.
General metrics
GET /v1/insights returns summary cards (posts, views, reactions, comments, engagement, followers…), the top posts, results per channel and the first-48-hour reading. Filters: from, to, channel, tag, type, compare=1 (previous period), sort, direction, page and limit. GET /v1/content lists everything already published, inside and outside Praeko.
Posts created outside Praeko (directly in the network's app or in Buffer) show up as origin: "external": Praeko picks up the last 48 hours, every 15 minutes per channel. POST /v1/insights/import (admin scope) imports the history; it is idempotent.
Retention, impressions and CTR
GET /v1/insights/retention?from=&to=&channel=&limit= returns, for each post in the period, views, reach, impressions, ctr, avgViewPercentage, avgWatchTimeSec, watchTimeMin and a retention block. limit goes from 1 to 200.
- YouTube: audience retention (YouTube Analytics API), thumbnail impressions and CTR as a percentage (YouTube Reporting API).
- Instagram: reach, watch time and skip rate (
skipRate), from the Meta API; there is no curve. - A number that does not exist comes back as
null, never 0, andretention.messagesays why.
States
| `state` | Meaning |
|---|---|
ready |
Data is ready. |
pending |
Not here yet: YouTube lags 2 to 3 days and the first impressions report can take up to 48 h. |
reauthorize |
The YouTube token lacks the yt-analytics.readonly scope. Reconnect the channel. Everything else keeps working. |
unavailable |
No data available for this channel or post. |
error |
Fetching failed (for example, the YouTube Analytics or Reporting API is not enabled in the Google Cloud project). |
The curve of one post
GET /v1/insights/:item/retention (:item is an item id) returns the item and curve: points with position (0 to 1 through the video), watched (audienceWatchRatio, above 1 when people rewatch) and relative (relativeRetentionPerformance, 0.5 is the median of videos of similar length).
Routes: /v1/insights and /v1/content.