Metrics
Obter métricas em tabelas e grades pela API
Com component datatable_v1 em POST /metrics/get-data, a métrica volta como dados tabulares, com colunas (metrics) e quebra por dimensão. Há também datagrid_v1 para grades, como os stories do Instagram. Uma API para todas as contas conectadas, sem integrar rede por rede.
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": "80e06171-759e-472e-9cff-25ae8e91e1e0",
"reference_key": "fb_ads:insights_by_campaign",
"component": "datatable_v1",
"metrics": [
"results",
"cost_per_results",
"spend",
"reach",
"impressions",
"ctr",
"cpc",
"cpm",
"frequency"
]
}
]
}O que dá para fazer
- Listar campanhas do Meta Ads com resultados, custo, gasto, alcance, impressões, CTR, CPC, CPM e frequência com fb_ads:insights_by_campaign.
- Escolher as colunas em metrics e a quebra em dimensions, usando os valores do catálogo GET /metrics/{integration_slug}.
- Pedir tabelas junto de números e gráficos na mesma chamada.
- Usar datagrid_v1 para grades, como os stories do Instagram.
Regras e limites
- Copie o item do catálogo para metrics[] e troque metrics e dimensions pelas chaves de meta.setup do catálogo se quiser outro recorte.
- Os itens do catálogo já trazem metrics e dimensions no formato aceito: copie-os como vêm.
- O resultado vem em data, sob o id (UUID) de cada métrica, no formato do component.
- Se uma métrica falhar sozinha, ela volta com um objeto de erro e as demais vêm 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). |
| metrics.reference_key | string | Sim | Métrica do catálogo cujo component é datatable_v1 ou datagrid_v1, como fb_ads:insights_by_campaign. |
| metrics.component | string | Sim | datatable_v1 para dados tabulares; datagrid_v1 para grades, como stories do Instagram. |
| metrics.metrics | array | Sim | As colunas pedidas (por exemplo spend, reach, ctr). |
| metrics.dimensions | array | Não | A quebra do resultado. Copie do item do catálogo. |
Para quem
Tabela de campanhas no seu produto
Liste as campanhas do cliente com gasto, alcance e CTR dentro da sua interface, sem integrar o Meta Ads.
Relatórios de performance de mídia paga
Monte o ranking de campanhas de cada cliente para o relatório mensal da agência.
Agentes que analisam campanhas
Um agente lê a tabela e aponta as campanhas com pior custo por resultado.
Perguntas frequentes
Qual a diferença entre datatable_v1 e datagrid_v1?
datatable_v1 entrega dados tabulares; datagrid_v1 entrega uma grade, como a de stories do Instagram. O catálogo de cada plataforma mostra qual component cada métrica usa.
Como quebro o resultado por campanha?
Use fb_ads:insights_by_campaign, o item do catálogo do Meta Ads que já vem com a dimensão de campanha, e copie metrics e dimensions dele.
Posso paginar a tabela?
A spec não descreve paginação nem ordenação para tabelas, então isso não é documentado aqui. O recorte é feito pelo período, pelas métricas e pelas dimensões.
Veja o Connect aplicado ao seu produto.
Teste por 15 dias sem cartão, ou mostre seu cenário ao nosso time.
