# Metrics, retention and CTR

> Read post metrics, retention, impressions and CTR with the Praeko API: GET /v1/insights, /v1/insights/retention and the retention curve of a post.

Source: https://praeko.app/docs/en/guides/insights

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, and `retention.message` says 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`](https://praeko.app/docs/en/api/insights) and [`/v1/content`](https://praeko.app/docs/en/api/content).