Post retention
GET /v1/insights/:item/retention scope read
Retention curve of one item (:item is the id of an item from /v1/insights: a post item or imported content) and its reach metrics. Same state and message as the list route.
Headers
Authorization: Bearer praeko_… and X-Praeko-Contract: en. Always send both.Parameters
| Name | In | Description |
|---|---|---|
item |
path | Id of the post item (the items[].id field of the GET /v1/posts/:id response). |
Example
curl "https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention" \
-H "Authorization: Bearer $PRAEKO_KEY" \
-H "X-Praeko-Contract: en"const res = await fetch("https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention", {
method: "GET",
headers: {
"Authorization": `Bearer ${process.env.PRAEKO_KEY}`,
"X-Praeko-Contract": "en",
},
});
console.log(res.status, await res.json());// O @praeko/sdk ainda não tem um método para esta rota: use o fetch (aba JavaScript).
const res = await fetch("https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention", {
method: "GET",
headers: {
"Authorization": `Bearer ${process.env.PRAEKO_KEY}`,
"X-Praeko-Contract": "en",
},
});
console.log(res.status, await res.json());import os
import requests
resp = requests.get(
"https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention",
headers={
"Authorization": f"Bearer {os.environ['PRAEKO_KEY']}",
"X-Praeko-Contract": "en",
},
)
print(resp.status_code, resp.json())<?php
$ch = curl_init('https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer " . getenv("PRAEKO_KEY"),
'X-Praeko-Contract: en',
],
]);
$resposta = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $resposta, PHP_EOL;
curl_close($ch);package main
import (
"fmt"
"io"
"net/http"
"os"
)
func main() {
req, err := http.NewRequest("GET", "https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention", nil)
if err != nil {
panic(err)
}
req.Header.Set("Authorization", "Bearer "+os.Getenv("PRAEKO_KEY"))
req.Header.Set("X-Praeko-Contract", "en")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
out, _ := io.ReadAll(resp.Body)
fmt.Println(resp.Status, string(out))
}require "net/http"
require "uri"
uri = URI("https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV['PRAEKO_KEY']}"
request["X-Praeko-Contract"] = "en"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.code, response.bodyusing System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Get, "https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("PRAEKO_KEY"));
request.Headers.Add("X-Praeko-Contract", "en");
using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention"))
.header("Authorization", "Bearer " + System.getenv("PRAEKO_KEY"))
.header("X-Praeko-Contract", "en")
.method("GET", HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode() + " " + response.body());
}
}http GET "https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention" \
"Authorization: Bearer $PRAEKO_KEY" \
"X-Praeko-Contract: en"This route has no dedicated SDK call yetThe example uses
fetch.No official SDKExample with the language's standard library (or HTTP client). Only the JavaScript SDK exists.
No official SDKExample with the language's standard library (or HTTP client). Only the JavaScript SDK exists.
No official SDKExample with the language's standard library (or HTTP client). Only the JavaScript SDK exists.
No official SDKExample with the language's standard library (or HTTP client). Only the JavaScript SDK exists.
No official SDKExample with the language's standard library (or HTTP client). Only the JavaScript SDK exists.
No official SDKExample with the language's standard library (or HTTP client). Only the JavaScript SDK exists.
Response
| Success status | When |
|---|---|
200 |
Success. |
{
"item": {
"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
},
"curve": [
{
"position": 0.01,
"watched": 1,
"relative": 0.8
},
{
"position": 0.5,
"watched": 0.42,
"relative": 0.55
},
{
"position": 1,
"watched": 0.1,
"relative": 0.3
}
]
},
"channels": [
{
"channelId": "01KA3V0R5D8M2WQ7X4HT9NZ1BF",
"network": "youtube",
"name": "Marcone's Channel",
"state": "ready",
"message": "Per-video retention, impressions and CTR, through the YouTube Analytics API."
}
]
}curve has up to 100 points: position from 0 to 1 along the video, watched (above 1 when viewers rewatch) and relative (0.5 = median of videos of similar length). 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
Sign in to try itThe live test uses your key and your account. It stays off when you are not signed in.
Question or mistake on this page? contato@praeko.appView .md