# Métricas de clique

> Leia cliques por link ou da conta inteira: resumo, série temporal, distribuição por país, cidade, dispositivo e origem, cliques individuais e exportação CSV.

Fonte: https://curtei.com/docs/api/metricas

Escopo: `analytics:read`

Todas as rotas aceitam `from` e `to` (ISO-8601 ou só a data; padrão: últimos 30 dias; até 400 dias), `timezone` (padrão `America/Sao_Paulo`) e `include_bots` (padrão `false`).

| Rota | Retorno |
| --- | --- |
| `GET /links/{id}/stats` | Total, únicos, bots, QR, último clique e top 5 de país, estado, dispositivo, sistema, navegador e canal |
| `GET /links/{id}/stats/timeseries?interval=hour\|day\|week\|month` | `[{ "t", "clicks", "unique", "bots" }]`, com zeros nos intervalos sem clique |
| `GET /links/{id}/stats/breakdown?dimension=...` | `[{ "key", "clicks", "unique", "pct" }]` |
| `GET /links/{id}/clicks` | Cliques individuais, mais recentes primeiro, sem IP |
| `GET /stats`, `/stats/timeseries`, `/stats/breakdown` | O mesmo somando todos os links; filtros `tag`, `campaign_id`, `link_ids[]` |
| `GET /stats/top-links?metric=clicks\|unique` | Ranking de links no período |
| `GET /stats/insights` | Destaques do período comparados ao anterior (canal, cidade, link que cresceu) |
| `POST /exports` → `GET /exports/{id}` | CSV ou NDJSON gerado em segundo plano; `download_url` vale 24 h |

Dimensões de `breakdown`: `country`, `region`, `city`, `device_type`, `os`, `browser`, `language`, `referer_host`, `referer_channel`, `utm_source`, `utm_medium`, `utm_campaign`, `as_org` (operadora) e `rule`.

```bash
curl "https://api.curtei.com/v1/links/{id}/stats/breakdown?dimension=city&from=2026-11-01&to=2026-11-13" \
  -H "Authorization: Bearer $CURTEI_TOKEN"
```

```json
{
  "period": {
    "from": "2026-11-01T00:00:00-03:00",
    "to": "2026-11-13T23:59:59-03:00",
    "timezone": "America/Sao_Paulo",
    "include_bots": false
  },
  "dimension": "city",
  "data": [
    {
      "key": "BR/SP/São Paulo",
      "clicks": 602,
      "unique": 511,
      "pct": 0.393
    },
    {
      "key": "BR/MG/Belo Horizonte",
      "clicks": 211,
      "unique": 190,
      "pct": 0.1377
    }
  ]
}
```

> Únicos = visitantes distintos por link por dia, somados no período. Cliques de robôs e de pré-visualização (WhatsApp, Telegram, Slack) ficam fora por padrão.