# Métricas

Impressões, alcance, visualizações, curtidas, comentários, compartilhamentos, salvamentos, cliques e taxa de engajamento de cada post, por rede; seguidores e médias por conta; e um resumo do espaço. Tudo requer o scope `posts:read` ([chaves limitadas](https://wyroapi.com/pt/docs/chaves)).

## Um post

```
curl https://wyroapi.com/v1/posts/post_abc123/metrics -H "Authorization: Bearer $WYRO_API_KEY"
```

```json
{
  "post_id": "post_abc123",
  "status": "published",
  "simulated": false,
  "totals": { "impressions": 15420, "reach": 12350, "views": 900, "likes": 342, "comments": 28, "shares": 45, "saves": 12, "clicks": 189, "engagement_rate": 2.76 },
  "targets": [
    {
      "account_id": "acc_ig1",
      "platform": "instagram",
      "available": true,
      "metrics": { "impressions": 15420, "reach": 12350, "views": 900, "likes": 342, "comments": 28, "shares": 45, "saves": 12, "clicks": null, "engagement_rate": 2.78 },
      "published_url": "https://www.instagram.com/p/…",
      "fetched_at": "2026-11-18T12:00:00.000Z"
    },
    {
      "account_id": "acc_tt1",
      "platform": "tiktok",
      "available": false,
      "reason": "syncing",
      "reason_text": "…",
      "metrics": null
    }
  ],
  "fetched_at": "2026-11-18T12:00:00.000Z",
  "stale": false,
  "next_refresh_at": "2026-11-18T13:00:00.000Z",
  "next_step": "…"
}
```

- Uma entrada por conta de destino. `null` numa métrica quer dizer que **essa rede não informa** (veja a tabela abaixo); `0` é um zero real.
- `available: false` vem com `reason` e um `reason_text` no idioma do espaço: `not_published` (agendado ou ainda saindo), `failed` (a publicação falhou ali), `syncing` (a rede ainda não entregou: consulte de novo em alguns minutos), `not_available` (essa rede ou esse post não dá métricas), `post_not_found` (apagado na rede), `temporarily_unavailable`.
- `engagement_rate` é uma porcentagem: (likes + comments + shares + saves) / (impressions, senão reach, senão views) × 100. `totals` soma as redes.
- `GET /v1/posts/{id}` (e a lista) também traz um `metrics` compacto com os totais quando existem, lido só do cache.

### Quão atualizadas

As redes atualizam as métricas cerca de uma vez por hora, então o wyro as guarda por **1 hora** e responde dali (rápido, e sem gastar os limites das redes). Depois dessa hora, a próxima leitura consulta de novo. Um post nunca é consultado mais de **uma vez a cada 15 minutos**: `?refresh=true` força uma nova leitura dentro da hora, com esse limite. `fetched_at` diz quando os números foram lidos, `stale: true` que têm mais de uma hora (não foi possível consultar a rede) e `next_refresh_at` quando pode acontecer a próxima leitura.

## Uma conta

```
curl "https://wyroapi.com/v1/accounts/acc_abc123/metrics?since=2026-11-01&until=2026-11-30" -H "Authorization: Bearer $WYRO_API_KEY"
```

- `followers`: `current`, `change` e `change_pct` no período, e `series` (um ponto por dia). As redes atualizam os seguidores uma vez por dia.
- `posts`: quantos saíram no período e quantos têm métricas; `totals` e `averages` (por post) das métricas; `best_post` (o de mais interações).
- `since` / `until`: YYYY-MM-DD (o dia inteiro, horário de Buenos Aires) ou ISO 8601. Padrão: os últimos 30 dias; no máximo 366.

## O espaço

`GET https://wyroapi.com/v1/analytics/overview` mantém todos os campos que já tinha e soma `performance`: posts **publicados** no período com métricas, `totals`, `by_platform`, os `top_posts` (5) e uma `series` diária (posts, impressions, reach, views, interactions).

## O que cada rede informa

| Rede | `impressions` | `reach` | `views` | `likes` | `comments` | `shares` | `saves` | `clicks` |
| --- | :-: | :-: | :-: | :-: | :-: | :-: | :-: | :-: |
| Instagram | sim | sim | sim | sim | sim | sim | sim | — |
| Facebook | sim | — | sim | sim | sim | sim | — | sim |
| TikTok | — | — | sim | sim | sim | sim | — | — |
| LinkedIn | sim | sim | — | sim | sim | sim | sim | sim |
| X | sim | — | sim | sim | sim | sim | sim | sim |
| Threads | — | — | sim | sim | sim | sim | — | — |
| YouTube | — | — | sim | sim | sim | — | — | — |
| Pinterest | sim | — | — | — | — | — | sim | sim |

O LinkedIn informa cliques em páginas de empresa e salvamentos em perfis pessoais. Os stories do Facebook não têm cliques.

## Modo de teste

Com uma chave de teste (ou em contas simuladas) as métricas são **simuladas**: números realistas que dependem do id do post (o mesmo post sempre dá os mesmos números) e crescem durante o primeiro ou segundo dia, com `simulated: true`. Nada é lido de nenhuma rede. Mostre como exemplo, nunca como resultados reais.

## Parceiros

Um parceiro atuando por um cliente (token de parceiro + `X-Wyro-External-Id`) lê as métricas desse cliente, e só as dele.

## Pelo agente (MCP)

`wyro_metricas`: sem argumentos, o último post publicado («como foi meu último post?»); com `post_id`, esse post; com `cuenta` (id da conta ou rede), o resumo da conta (`desde` / `hasta` para o período). Responde no idioma do usuário.

## No painel

O detalhe de cada post mostra as métricas por rede e quando foram atualizadas; o Início tem um bloco **Desempenho** do mês (interações, impressões e visualizações, taxa de engajamento, melhor post), e Contas mostra os seguidores de cada conta.
