Skip to content
Sign in Waitlist
Docs/API reference/Insights/Retention, impressions and CTR

Retention, impressions and CTR

GET /v1/insights/retention scope read

Retention (% watched and average watch time), impressions and CTR from YouTube, and skip rate from Instagram, per post. Data the network does not provide comes as null, with the reason in retention.message. Requires the yt-analytics.readonly permission, which the YouTube connection already requests (channels connected before it was added must reauthorize once).

HeadersAuthorization: Bearer praeko_… and X-Praeko-Contract: en. Always send both.

Example

curl "https://praeko.app/v1/insights/retention" \
  -H "Authorization: Bearer $PRAEKO_KEY" \
  -H "X-Praeko-Contract: en"

Response

Success status When
200 Success.
Response 200
{
  "period": {
    "from": "2026-10-08T14:02:11.482Z",
    "to": "2026-11-07T14:02:11.482Z"
  },
  "channels": [
    {
      "channelId": "01KA3V0R5D8M2WQ7X4HT9NZ1BF",
      "network": "youtube",
      "name": "Marcone's Channel",
      "state": "ready",
      "message": "Per-video retention, impressions and CTR, through the YouTube Analytics API."
    }
  ],
  "total": 1,
  "items": [
    {
      "id": "youtube:dQw4w9WgXcQ",
      "network": "youtube",
      "channelId": "01KA3V0R5D8M2WQ7X4HT9NZ1BF",
      "title": "The test that only failed on Mondays",
      "type": "short",
      "publishedAt": "2026-11-01T12:00:00Z",
      "url": "https://youtu.be/dQw4w9WgXcQ",
      "origin": "imported",
      "views": 1240,
      "reach": null,
      "impressions": 9800,
      "ctr": 5.5,
      "avgViewPercentage": 47.5,
      "avgWatchTimeSec": 31.2,
      "watchTimeMin": 2500.5,
      "retention": {
        "state": "ready",
        "source": "youtube-analytics",
        "collectedAt": "2026-11-07T15:40:03.120Z",
        "points": 100
      }
    }
  ],
  "collection": {
    "last": "2026-11-07T14:02:11.482Z"
  }
}

A number the network has not delivered yet comes as null, never 0. retention.state: ready, pending, reauthorize, unavailable or error. channels[].message is free text the server writes in Portuguese; the example shows it in English.

Errors

No errors specific to this route besides the common ones.

Errors on any route

Status code When
401 unauthorized The Authorization: Bearer … header is missing.
401 invalid_api_key The key does not exist.
401 revoked_api_key The key has been revoked.
401 expired_api_key The key has expired.
403 forbidden The key's scope is not enough for this route (see the scope badge).
429 rate_limited The per-minute request limit was exceeded.

The body of every error is { "error": { "code", "message", "details"? } }. See all error codes.

Try it

Try it

The live test uses your key and your account. It stays off when you are not signed in.

Sign in to try it
Question or mistake on this page? contato@praeko.appView .md

Type to search pages, routes and error codes.