Métricas, retenção e CTR
As métricas dos posts e o que o YouTube e o Instagram informam sobre quem assistiu.
Métricas gerais
GET /v1/insights devolve cartões (posts, views, reações, comentários, engajamento, seguidores…), os melhores posts, o resultado por canal e a leitura das primeiras 48 h. Filtros: from, to, channel, tag, type, compare=1 (período anterior), sort, direction, page e limit. GET /v1/content lista tudo o que já foi publicado, dentro e fora do Praeko.
Posts criados fora do Praeko (direto no app da rede ou no Buffer) entram como origin: "external": o Praeko os registra a partir das últimas 48 h, a cada 15 minutos por canal. POST /v1/insights/import (escopo admin) importa o histórico; é idempotente.
Retenção, impressões e CTR
GET /v1/insights/retention?from=&to=&channel=&limit= traz, por post do período, views, reach, impressions, ctr, avgViewPercentage, avgWatchTimeSec, watchTimeMin e um bloco retention. limit vai de 1 a 200.
- YouTube: retenção da audiência (YouTube Analytics API), impressões da miniatura e CTR em porcentagem (YouTube Reporting API).
- Instagram: alcance, tempo assistido e taxa de saída (
skipRate), pela API da Meta; não há curva. - Número que não existe vem
null, nunca 0, eretention.messagediz por quê.
Estados
| `state` | Significa |
|---|---|
ready |
Dados prontos. |
pending |
Ainda não chegaram: o YouTube atrasa de 2 a 3 dias e o primeiro relatório de impressões pode levar até 48 h. |
reauthorize |
O token do YouTube não tem o escopo yt-analytics.readonly. Reconecte o canal. O resto segue funcionando. |
unavailable |
Sem dados disponíveis para este canal ou post. |
error |
Falha ao buscar (por exemplo, a API do YouTube Analytics ou Reporting não está habilitada no projeto do Google Cloud). |
A curva de um post
GET /v1/insights/:item/retention (o :item é o id de um item) devolve o item e curve: pontos com position (de 0 a 1 do vídeo), watched (audienceWatchRatio, acima de 1 quando alguém reassiste) e relative (relativeRetentionPerformance, 0,5 é a mediana de vídeos de duração parecida).
Rotas: /v1/insights e /v1/content.