# Consultar analytics

Métricas, dimensões e filtros com o mesmo recorte da dashboard.

## Consultar o relatório

GET /v1/account/sites/:siteId/analytics exige analytics:read e retorna site, período, métricas, série diária, linhas da dimensão e cobertura.


### cURL



```bash
curl "https://api.pulsant.app/v1/account/sites/$PULSANT_SITE_ID/analytics?days=7" \
  -H "Authorization: Bearer $PULSANT_SECRET_KEY"
```


### Node.js / fetch



```ts
const response = await fetch(
  `https://api.pulsant.app/v1/account/sites/${process.env.PULSANT_SITE_ID}/analytics?days=7`,
  { headers: { Authorization: `Bearer ${process.env.PULSANT_SECRET_KEY}` } }
);
if (!response.ok) throw new Error(`Falha na consulta: ${response.status}`);
const report = await response.json();
```



## Período e paginação

Datas explícitas ficam fixas. Quando elas não são enviadas, days define uma janela relativa que avança a cada consulta.


| Parâmetro | Uso |
| --- | --- |
| days | De 1 a 366 dias; padrão 30 |
| from / to | Instantes ISO 8601; intervalo máximo de 366 dias |
| dimension | path, referrer, channel, campaign, country, region, city, browser, os, device, hostname ou event |
| search | Busca na dimensão; até 100 caracteres |
| page | Página a partir de 1; até 20 linhas por página; confira hasMore |



## Combinar filtros

Envie filters como JSON serializado, com até oito condições combinadas por E. Os operadores são eq, neq e contains.


```ts
const filters = [{ dimension: 'country', operator: 'eq', value: 'BR' }];
const query = new URLSearchParams({
  days: '7', dimension: 'path', filters: JSON.stringify(filters),
});
// Acrescente query à rota de analytics no seu backend.
```



## Consultar apenas uma dimensão

GET /v1/account/sites/:siteId/analytics/breakdown usa os mesmos filtros e período, retornando rows, dimension, page e hasMore. Essa rota evita recalcular os totais e a série para cada card.


```bash
curl "https://api.pulsant.app/v1/account/sites/$PULSANT_SITE_ID/analytics/breakdown?days=7&dimension=browser" \
  -H "Authorization: Bearer $PULSANT_SECRET_KEY"
```



## Interpretar as contagens

Visitantes são distintos no recorte, e uma pessoa pode aparecer em várias linhas de dimensões diferentes. Online considera atividade nos últimos cinco minutos, com os filtros aplicados. Dias sem dados entram como zero na série; ausência de base para uma razão aparece como null.


- [Definições das métricas](/metrics)