# Métricas > Leia o que os seus componentes fizeram com GET /v1/metrics, uma janela de entregas do loader e conversões por site, componente e versão, com a fonte e a confiança de cada número. Janelas de até 7 dias em horas ou 90 dias em dias; tudo o que vem de eventos do navegador (impressões, interações, eventos próprios e as taxas) é forjável (`forgeable`). `GET /v1/metrics` responde o que os componentes do seu workspace fizeram em uma janela, balde a balde. Esta página diz o que é cada número e quanto confiar nele, para que ninguém leia uma contagem de entregas, ou de eventos do navegador, como se fosse um público verificado. ## O que é medido | Métrica | Fonte | Confiança | O que é | | ------------------- | ------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `loader_deliveries` | `loader_hits` | `forgeable` | Vezes que a borda entregou o loader a uma página de um site seu: tráfego humano, em um hostname que o site não bloqueia. **Não** é uma impressão verificada. | | `conversions` | `submissions` | `counted` | Envios aceitos (não spam) de uma coleção do componente, contados das linhas que o Taggor guarda. É a definição padrão de conversão. | | `impressions` | `component_events` | `forgeable` | Componentes renderizados no navegador de um visitante: o loader avisa cada componente montado. Só tráfego humano. | | `interactions` | `component_events` | `forgeable` | Eventos que um componente declarou em `events` e emitiu, informados pelos navegadores dos visitantes: no máximo 30 por componente por página, amostrados por `eventSampleRate`, então uma estimativa. | | `custom_events` | `component_events` | `forgeable` | Eventos que um componente declarou em `data.track` e enviou com `track`, informados, limitados e amostrados do mesmo jeito. | | `interaction_rate` | `component_events` | `forgeable` | `interactions / impressions`, como fração. `null` quando não há impressões. | | `conversion_rate` | `component_events` | `forgeable` | `conversions / impressions`, como fração (`0.0734` é 7,34 %). `null` quando não há impressões. | `forgeable` quer dizer que qualquer pessoa que conheça a chave do site (ela é pública, vai no seu HTML) pode aumentar a contagem pedindo o loader; por isso o Taggor nunca corta nem cobra só por ela. `counted` quer dizer linhas no nosso banco. Tudo o que vem de eventos do navegador também é `forgeable`, a taxa de conversão inclusive: uma taxa nunca é `counted`, mesmo quando o numerador é (`conversion_rate` divide envios guardados por impressões forjáveis). Não a apresente como taxa verificada. Uma métrica sem dado é `null` e nunca `0`. O array `metrics` de toda resposta repete isto: cada item tem `source`, `trust`, `available` e, quando não está disponível, um `reason` (`no_event_source`, `reader_unavailable` ou `not_attributable`). ## Peça uma janela ```bash curl -s -H "Authorization: Bearer $TAGGOR_API_KEY" \ "$TAGGOR_API_URL/v1/metrics?granularity=day&group_by=version" ``` | Parâmetro | Significado | | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `from`, `to` | A janela `[from, to)`, RFC 3339. Padrão: `to` é agora e `from` é 7 dias (`day`) ou 24 horas (`hour`) antes. | | `granularity` | `hour` (janela de até 7 dias) ou `day` (até 90 dias, que é quanto o dado é guardado). Padrão `day`. | | `group_by` | `site`, `component`, `version`, `country`, `device`, `hostname` ou `event` (veja "Recortes" abaixo). | | `site_id`, `component_id`, `version_id` | Restringe a um dos seus. Um site que não é seu dá `404`. | | `environment` | `production` (padrão) ou `staging`: os sites de teste ficam à parte, como no seu uso. | A resposta tem `totals`, uma `series` com um ponto por balde (com zeros onde a fonte respondeu e não achou nada) e, com `group_by`, `groups`, cada um com seus `totals` e os baldes que têm dado. Agrupadas por site, componente ou versão, as `conversions` somam o total. ## Recortes | `group_by` | O que é recortado | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `site` | Todas as métricas. | | `component`, `version` | `conversions`. As entregas do loader e as métricas do navegador vêm `null` por grupo (o total continua com elas). | | `country` | As métricas do navegador, pelo país de duas letras que a rede informa para o pedido. Nenhum endereço IP é guardado. | | `device` | As métricas do navegador, por uma de quatro classes: `mobile`, `desktop`, `tablet` ou `other`. Nenhum user agent é guardado. | | `hostname` | As métricas do navegador, pelo hostname da página em que o componente estava. | | `event` | `interactions` e `custom_events`, pelo nome do evento que o componente informou. | Uma métrica que um recorte não consegue cortar vem `null` por grupo, nunca `0`, e o `breakdown_available` dela é `false`. Um grupo dos quatro últimos tem `totals` e uma `series` vazia. O grupo `unknown` reúne os eventos que vieram sem valor (um pedido para o qual a rede não informou país). Um filtro `component_id` ou `version_id` deixa as entregas do loader e as métricas do navegador `null`, então os quatro últimos recortes não respondem grupos com ele. Se o leitor do Analytics Engine estiver fora, essas métricas vêm `null` com `reader_unavailable` e as conversões continuam respondendo. ## Amostragem e limites Em alto volume o Analytics Engine guarda um ponto para vários eventos e registra o peso em `_sample_interval`. Toda contagem de entregas aqui é uma **soma de pesos**, nunca uma contagem de linhas; assim um conjunto amostrado ainda dá uma estimativa do total real. As conversões vêm de um banco e não são amostradas. - No máximo 10.000 células (grupos vezes baldes) por resposta: um `group_by=site` que passaria disso dá `400` pedindo uma janela menor, dias em vez de horas ou um `site_id`. `truncated: true` quer dizer que uma fonte cortou a resposta; leia os números como um piso. - No máximo 200 grupos são listados. - 30 requisições por minuto por credencial (a classe de limite `metrics`). - Exige o escopo `metrics:read`; todo papel o tem, inclusive o de leitor. - Os números ficam um pouco atrás (segundos) e são aproximados; a mesma janela lida de novo em um minuto pode vir de um cache. ## Privacidade Tudo acima é contagem: nenhum identificador de visitante, endereço IP ou user agent é guardado ou devolvido. Veja [Formulários e dados](https://taggor.dev/docs/pt-br/forms-and-data.md) para o que um envio guarda, que é seu. ## Vem depois As suas próprias definições de conversão ainda não entram nestes números; esta página dirá quando passarem a entrar. Até lá, `conversions` é a medida de resultado. ## Pelo terminal e por um agente `taggor metrics` mostra os mesmos números desta rota: uma linha por métrica com a fonte e a confiança, e `--json` imprime a resposta da rota sem mudar nada. Flags: `--from`, `--to`, `--granularity`, `--group-by`, `--site`, `--component`, `--version`, `--environment`. Um agente ligado ao servidor MCP tem a tool `get_metrics` (escopo `metrics:read`), que diz o mesmo: números de eventos do navegador são `forgeable` (forjáveis).