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

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 do catálogo cujo component é datatable_v1 ou datagrid_v1, como fb_ads:insights_by_campaign.
metrics.componentstringSimdatatable_v1 para dados tabulares; datagrid_v1 para grades, como stories do Instagram.
metrics.metricsarraySimAs colunas pedidas (por exemplo spend, reach, ctr).
metrics.dimensionsarrayNãoA 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.

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.