# Retenção de um post > Retenção de um post: GET /v1/insights/:item/retention. Curva de retenção de um post (:item é o id do post) e as métricas de alcance dele. Mesmo estado e mensagem da rota de lista. Fonte: https://praeko.app/docs/api/insights/post-retention `GET /v1/insights/:item/retention` · escopo mínimo: read Curva de retenção de um post (`:item` é o id do post) e as métricas de alcance dele. Mesmo estado e mensagem da rota de lista. > **Cabeçalhos** `Authorization: Bearer praeko_…` e `X-Praeko-Contract: en`. Sempre envie os dois. ## Parâmetros | Nome | Onde | Descrição | |---|---|---| | `item` | caminho | Id do item do post (campo `items[].id` da resposta de `GET /v1/posts/:id`). | ## Exemplo **curl** ```bash curl "https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention" \ -H "Authorization: Bearer $PRAEKO_KEY" \ -H "X-Praeko-Contract: en" ``` **JavaScript** ```js 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()); ``` **Node** ```js // 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()); ``` **Python** ```python 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** ```php '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); ``` **Go** ```go 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)) } ``` **Ruby** ```ruby 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.body ``` **C#** ```csharp using 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()}"); ``` **Java** ```java 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 response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.statusCode() + " " + response.body()); } } ``` **HTTPie** ```bash http GET "https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention" \ "Authorization: Bearer $PRAEKO_KEY" \ "X-Praeko-Contract: en" ``` > Esta rota ainda não tem chamada própria no SDK: O exemplo usa `fetch`. ## Resposta | Status de sucesso | Quando | |---|---| | `200` | Sucesso. | **Resposta 200** ```json { "item": { "id": "youtube:dQw4w9WgXcQ", "network": "youtube", "channelId": "01KA3V0R5D8M2WQ7X4HT9NZ1BF", "title": "O teste que só falhava na segunda", "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": "Canal do Marcone", "state": "ready", "message": "Retenção por vídeo, impressões e CTR, pela API do YouTube Analytics." } ] } ``` `curve` tem até 100 pontos: `position` de 0 a 1 do vídeo, `watched` (acima de 1 quando o público reassiste) e `relative` (0,5 = mediana de vídeos de duração parecida). ## Erros Sem erros específicos desta rota além dos comuns. ### Erros de qualquer rota | Status | code | Quando | |---|---|---| | 401 | `unauthorized` | Faltou o cabeçalho `Authorization: Bearer …`. | | 401 | `invalid_api_key` | A chave não existe. | | 401 | `revoked_api_key` | A chave foi revogada. | | 401 | `expired_api_key` | A chave expirou. | | 403 | `forbidden` | O escopo da chave não basta para esta rota (veja o selo de escopo). | | 429 | `rate_limited` | Passou do limite de requisições por minuto. | O corpo de todo erro é `{ "error": { "code", "message", "details"? } }`. Veja [todos os códigos](https://praeko.app/docs/guides/errors-and-limits). ## Testar > **Testar**: o teste ao vivo exige entrar na conta. Aqui ele fica desligado.