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

CampoTipoObrigatórioDescrição
customer_integrationstringSimUUID da conexão do cliente de onde as métricas são lidas. Uma por chamada.
startstringSimInício do período (YYYY-MM-DD). Deve ser menor ou igual a end.
endstringSimFim do período (YYYY-MM-DD).
comparison_startstringNãoInício do período de comparação (YYYY-MM-DD). Só é considerado se comparison_end também for enviado.
comparison_endstringNãoFim do período de comparação (YYYY-MM-DD).
client_timezonestringNãoFuso horário, como America/Sao_Paulo (padrão).
metricsarraySimLista 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}.

Relacionadas

Ver tudo que dá para fazer em Metrics

Veja o Connect aplicado ao seu produto.

Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.