Pular para o conteúdo
Entrar Lista de espera
Docs/Referência da API/Insights/Retenção de um post

Retenção de um post

GET /v1/insights/:item/retention escopo 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çalhosAuthorization: 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 "https://praeko.app/v1/insights/01KA3W2Y6J9D3BNF7G2K5PQS8A/retention" \
  -H "Authorization: Bearer $PRAEKO_KEY" \
  -H "X-Praeko-Contract: en"

Resposta

Status de sucesso Quando
200 Sucesso.
Resposta 200
{
  "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.

Testar

Testar

O teste ao vivo usa a sua chave e a sua conta. Para quem não entrou, fica desligado.

Entre para testar
Dúvida ou erro nesta página? contato@praeko.appVer .md

Digite para buscar páginas, rotas e códigos de erro.