Pular para o conteúdo
Entrar Lista de espera
Docs/Referência da API/Insights/Retenção, impressões e CTR

Retenção, impressões e CTR

GET /v1/insights/retention escopo read

Retenção (% assistida e tempo médio), impressões e CTR do YouTube e taxa de pulo do Instagram, por post. Dado que a rede não entrega vem null, com o motivo em retention.message. Exige a permissão yt-analytics.readonly, que a conexão do YouTube já pede (canais conectados antes dela precisam reautorizar uma vez).

CabeçalhosAuthorization: Bearer praeko_… e X-Praeko-Contract: en. Sempre envie os dois.

Exemplo

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

Resposta

Status de sucesso Quando
200 Sucesso.
Resposta 200
{
  "period": {
    "from": "2026-10-08T14:02:11.482Z",
    "to": "2026-11-07T14:02:11.482Z"
  },
  "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."
    }
  ],
  "total": 1,
  "items": [
    {
      "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
      }
    }
  ],
  "collection": {
    "last": "2026-11-07T14:02:11.482Z"
  }
}

Número que a rede ainda não entregou vem null, nunca 0. retention.state: ready, pending, reauthorize, unavailable ou error.

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.