Metrics

Obter dados de gráficos de métricas pela API

O component define o formato do resultado. Com chart_v1 em POST /metrics/get-data, a métrica volta como dados de gráfico (linha, pizza, barra) que o seu front renderiza com a biblioteca que quiser. Nada de coletar e agregar por plataforma.

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",
  "metrics": [
    {
      "id": "f35a44ce-dac5-4188-aace-5c44a8952176",
      "reference_key": "ig:followers_gender",
      "component": "chart_v1",
      "metrics": [
        "followers"
      ],
      "dimensions": [
        "gender"
      ]
    }
  ]
}

O que dá para fazer

  • Pedir métricas em formato de gráfico com component chart_v1, junto de number_v1 e tabelas na mesma chamada.
  • Descobrir quais métricas são gráficos no catálogo GET /metrics/{integration_slug}, que traz o component padrão de cada uma.
  • Combinar um gráfico com um período de comparação (comparison_start e comparison_end).
  • Usar a versão assíncrona (get-data-async) para gráficos de períodos longos.

Regras e limites

  • Copie o item do catálogo para metrics[]: cada item de data já é um item válido da requisição.
  • O formato do resultado depende do component pedido; o payload é aberto, então leia o resultado de cada métrica pela chave id.
  • Se uma métrica falhar sozinha, ela volta com um objeto de erro (invalid_metrics_combination, no_data_in_period, internal_error ou expired_token) e as demais vêm com status 200.
  • Cada chamada lê uma conexão (customer_integration) e exige o x-customer-token do cliente.
  • No período de teste, start volta no máximo 62 dias e metrics aceita até 15 itens.

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).
metrics.reference_keystringSimMétrica cujo catálogo indica chart_v1, como ig:followers_gender.
metrics.componentstringSimUse chart_v1 para receber os dados no formato de gráfico.
metrics.metricsarraySimOs valores pedidos dentro da métrica. Copie do item do catálogo.
metrics.idstringSimUUID gerado por você; é a chave do resultado na resposta.

Para quem

  • Painéis de desempenho no seu SaaS

    Mostre evolução de alcance ou gasto em gráficos de linha dentro do seu produto, com dados vindos da conta conectada do cliente.

  • Relatórios de agência

    Monte páginas de relatório com gráficos por plataforma sem integrar cada API de rede social.

  • Agentes de IA com contexto visual

    Um agente busca a série de dados de um gráfico e descreve a tendência ao usuário.

Perguntas frequentes

Como sei se uma métrica vem como gráfico?

No catálogo GET /metrics/{integration_slug}, cada item traz o component padrão. As que vêm com chart_v1 retornam dados de gráfico.

A API desenha o gráfico?

Não. Ela devolve os dados no formato chart_v1; a renderização fica com o seu front-end.

Posso misturar gráficos e números na mesma chamada?

Sim. Cada item de metrics[] tem o seu component, e cada resultado volta sob o id do item.

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.