# Métricas, retenção e CTR

> Ler métricas, retenção, impressões e CTR dos posts pela API do Praeko: GET /v1/insights, /v1/insights/retention e a curva de retenção de um post.

Fonte: https://praeko.app/docs/guides/insights

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, e `retention.message` diz 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`](https://praeko.app/docs/api/insights) e [`/v1/content`](https://praeko.app/docs/api/content).