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
| 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). |
| metrics.reference_key | string | Sim | Métrica cujo catálogo indica chart_v1, como ig:followers_gender. |
| metrics.component | string | Sim | Use chart_v1 para receber os dados no formato de gráfico. |
| metrics.metrics | array | Sim | Os valores pedidos dentro da métrica. Copie do item do catálogo. |
| metrics.id | string | Sim | UUID 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.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
