> ## Documentation Index
> Fetch the complete documentation index at: https://docs.morada.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Analytics agregado
> Reproduza os dashboards de Conversas e Talk no seu BI a partir de componentes aditivos — você recebe as contagens, você divide.
## O que é o analytics agregado
O analytics agregado (`GET /v1/analytics/*`) entrega os **mesmos números dos dashboards** de Conversas e Talk da plataforma, mas em um formato pronto para o seu BI: linhas agregadas por período × dimensão, calculadas a partir dos seus dados de conversas e tickets.
Diferente dos [relatórios operacionais](/api-reference/export/relatorios), aqui as linhas já vêm **agregadas** — uma linha por balde de tempo e combinação de dimensões, não uma linha por evento.
São três endpoints: [conversas](/api-reference/export/analytics-conversations), [tickets](/api-reference/export/analytics-tickets) e um endpoint barato de [frescor](/api-reference/export/analytics-freshness) para consultar quando os dados foram atualizados pela última vez.
## O princípio dos componentes aditivos
A regra central do analytics: **entregamos numerador e denominador; você faz a divisão.** Nenhuma taxa, média ou percentual chega pré-calculado.
Uma taxa de resposta, por exemplo, não vem como `0.83`. Vêm as duas contagens — `conversations_answered` e `conversations_started` — e você computa `SUM(conversations_answered) / SUM(conversations_started)` no seu BI, sobre o recorte que quiser.
Nunca calcule uma taxa fazendo a média das taxas diárias. Isso dá peso igual a dias com volumes diferentes e produz um número errado. Some os componentes e divida as somas: `SUM(numerador) / SUM(denominador)`.
O mesmo vale para as médias de SLA do Talk. Cada média chega como um **par soma+contagem**, e a soma carrega a unidade no nome — em **segundos** (por exemplo `first_response_sum_seconds` e `first_response_count`). A média é `SUM(sum) / SUM(count)` em segundos; divida ainda por 60 para minutos.
## Grão: dia de São Paulo × dimensão
O grão canônico é o **dia do calendário de São Paulo** (`America/Sao_Paulo`) do timestamp que dirige cada métrica. Cada linha combina esse dia com as dimensões que você pedir em `group_by`.
* **`tz`** controla o fuso do agrupamento por dia. O padrão é `America/Sao_Paulo`; `UTC` também é aceito.
* **`group_by`** é uma lista separada por vírgulas de dimensões permitidas por métrica (por exemplo `agent_type,source` em conversas). Cada dimensão agrupada aparece como uma chave adicional em cada linha.
### Dia, semana e mês
`day` é o grão canônico. `week` (segunda-feira ISO) e `month` são o **mesmo rollup** somado sobre os dias — sem armazenamento separado, sem grão sub-diário. Isso só é válido porque **toda métrica exposta é aditiva** (uma contagem ou uma soma): semana e mês são apenas `SUM` sobre os dias.
Não há paginação por cursor no analytics: uma atualização de ETL no meio da paginação mudaria os valores dos baldes e quebraria a estabilidade do cursor. Em vez disso, as chamadas são limitadas por um teto rígido de intervalo (**366 dias** sem agrupamento, **92 dias** com agrupamento) e por um limite máximo de linhas. Para períodos maiores, quebre em várias chamadas.
## Escopo padrão de conversas (agent\_type)
Sem parâmetros, o endpoint de conversas retorna o **mesmo recorte que os painéis mostram por padrão** — as conversas do seu agente de IA no WhatsApp. Assim os números batem com a plataforma sem nenhuma configuração.
Para ampliar (ou restringir) esse recorte, informe o filtro **`agent_type`** com uma lista separada por vírgulas dos tipos de agente que você quer incluir. Os valores válidos são os mesmos que aparecem na dimensão `agent_type` dos próprios resultados (agrupe por `agent_type` para vê-los). `agent_type` sobrescreve o padrão.
Se os seus números não baterem com o painel, verifique primeiro o `agent_type`: o padrão é o que garante a paridade. Só amplie quando quiser deliberadamente incluir outros tipos de agente.
## Frescor: as\_of e stale
O `data_lake` é atualizado por ETL a cada 6 horas. Por isso **toda resposta de analytics carrega o frescor**:
* **`as_of`** — o momento (ISO 8601) da última execução de ETL bem-sucedida daquele metricset. `null` quando desconhecido.
* **`stale`** — `true` quando os dados estão defasados (mais que \~2× a cadência de 6h, ou seja, quando uma execução foi pulada/falhou) ou quando o frescor é desconhecido.
* O header **`X-Data-As-Of`** repete o `as_of` da resposta.
A política é **servir com aviso, nunca falhar**: mesmo defasada, a resposta volta com `200` e `stale: true`. Um carimbo ausente é lido como `{ as_of: null, stale: true }` — nunca como atualizado. Use o endpoint de [frescor](/api-reference/export/analytics-freshness) para consultar o `as_of` de cada metricset de forma barata antes de puxar.
Cada metricset carrega o seu próprio `as_of`: uma execução parcial de ETL pode deixar conversas atualizado e tickets defasado. Por isso os endpoints nunca combinam duas fontes carimbadas independentemente.
## Métricas NÃO aditivas
Nem tudo o que os dashboards mostram pode ser somado livremente. Estas métricas exigem cuidado — sempre reconstrua a partir dos componentes exportados, nunca some o resultado final:
Taxa de resposta, taxa de agendamento, taxa de transferência, médias de SLA (tempo de atribuição, primeira resposta, handle time), CSAT. Recompute como `SUM(numerador) / SUM(denominador)` — nunca faça a média das taxas diárias.
`tickets_in_service` e `status_id` refletem o estado no instante do snapshot do ETL — um ticket pode mudar de balde numa execução posterior. São aditivos apenas dentro de um mesmo snapshot.
Quando uma conversa tem vários produtos/empreendimentos (ou vários skills), ela aparece em mais de um balde da dimensão. Somar ao longo dessa dimensão superconta o total distinto — a aditividade só vale no eixo do tempo dentro de um mesmo balde.
Contagens de conversas distintas (razões de transferência), dias ativos e etapas de funil (iniciada → transferida → qualificada → respondida) são subconjuntos aninhados, não partições. Reconstrua a partir das flags/componentes exportados; não some o resultado.
Rankings de melhor/pior atendente ou empreendimento e cortes Top-N são derivados. Exportamos a dimensão completa (sem corte) com os pares soma+contagem por entidade — o seu BI aplica o limite mínimo e ordena.
Deltas entre períodos e taxas normalizadas por dias ativos nunca são entregues. Junte os componentes e calcule no BI.
## Referência e playground
Consulte [Conversas](/api-reference/export/analytics-conversations), [Tickets](/api-reference/export/analytics-tickets) e [Frescor](/api-reference/export/analytics-freshness) para todos os parâmetros, as métricas expostas, os formatos de resposta e os códigos de erro — e para testar as chamadas direto no playground.