Metrics
Comparar períodos de métricas pela API
Em POST /metrics/get-data você manda o período principal e, se quiser, um período de comparação. A resposta já traz o valor atual e o anterior, então o seu produto mostra variação sem uma segunda chamada. Sem OAuth, sem revisão de app, sem renovar token.
A chamada
POST /api/metrics/get-data
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"customer_integration": "<connection uuid>",
"start": "2026-08-01",
"end": "2026-08-31",
"comparison_start": "2026-07-01",
"comparison_end": "2026-07-31",
"metrics": [
{
"id": "f35a44ce-dac5-4188-aace-5c44a8952176",
"reference_key": "fb_ads:spend",
"component": "number_v1",
"metrics": [
"spend"
]
}
]
}O que dá para fazer
- Comparar o mês atual com o anterior, ou qualquer par de períodos, numa única chamada.
- Pedir várias métricas de uma vez, cada uma com o seu component.
- Ajustar o fuso com client_timezone para que os dias fechem como o seu cliente espera.
- Usar a versão assíncrona (get-data-async) com os mesmos campos de comparação em períodos longos.
Regras e limites
- comparison_start só é considerado se comparison_end também for enviado.
- No exemplo da spec, um number_v1 volta com value (período atual) e previous_value (período de comparação).
- O resultado vem no objeto data, com o id (UUID) de cada métrica como chave.
- Se uma métrica falhar sozinha, ela volta com um objeto de erro (por exemplo no_data_in_period) e as outras vêm normalmente, com status 200.
- Cada chamada lê uma conexão (customer_integration) e exige o x-customer-token do cliente.
Campos principais
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| customer_integration | string | Sim | UUID da conexão do cliente de onde as métricas são lidas. Uma por chamada. |
| start | string | Sim | Início do período (YYYY-MM-DD). Deve ser menor ou igual a end. |
| end | string | Sim | Fim do período (YYYY-MM-DD). |
| comparison_start | string | Não | Início do período de comparação (YYYY-MM-DD). Só é considerado se comparison_end também for enviado. |
| comparison_end | string | Não | Fim do período de comparação (YYYY-MM-DD). |
| client_timezone | string | Não | Fuso horário, como America/Sao_Paulo (padrão). |
| metrics | array | Sim | Lista de métricas pedidas, ao menos uma. Cada item traz id, reference_key, component e metrics. |
Para quem
Cartões de variação em dashboards
Seu painel mostra gasto ou seguidores com a seta de alta ou queda sobre o período anterior, a partir de uma só resposta.
Relatórios mensais de agência
Gere o comparativo mês a mês de cada cliente sem calcular a diferença do seu lado.
Agentes que explicam variações
Um agente lê atual e anterior e escreve a análise do que mudou, com os números vindos da API.
Perguntas frequentes
Como peço a comparação?
Envie comparison_start e comparison_end junto com start e end em POST /metrics/get-data. Se mandar só um dos dois, a comparação não é considerada.
O período de comparação precisa ter o mesmo tamanho?
A spec não impõe isso: você escolhe as duas datas. Para uma comparação justa, use períodos do mesmo tamanho.
Funciona com todas as métricas?
Depende da métrica e do component. O exemplo da spec mostra number_v1 voltando com value e previous_value. Teste a métrica que você precisa no catálogo GET /metrics/{integration_slug}.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
