Metrics

Obtener métricas en tablas y grillas con la API

Con el component datatable_v1 en POST /metrics/get-data, la métrica vuelve como datos tabulares, con columnas (metrics) y desglose por dimensión. También existe datagrid_v1 para grillas, como los stories de Instagram. Una API para todas las cuentas conectadas, sin integrar red por red.

La llamada

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"
      ]
    }
  ]
}

Qué puedes hacer

  • Listar campañas de Meta Ads con resultados, costo por resultado, gasto, alcance, impresiones, CTR, CPC, CPM y frecuencia con fb_ads:insights_by_campaign.
  • Elegir las columnas en metrics y el desglose en dimensions, con los valores del catálogo GET /metrics/{integration_slug}.
  • Pedir tablas junto a números y gráficos en la misma llamada.
  • Usar datagrid_v1 para grillas, como los stories de Instagram.

Reglas y límites

  • Copia el ítem del catálogo en metrics[] y cambia metrics y dimensions por claves de meta.setup del catálogo si quieres otro recorte.
  • Los ítems del catálogo ya traen metrics y dimensions en el formato aceptado: cópialos tal cual.
  • El resultado viene en data, bajo el id (UUID) de cada métrica, en el formato del component.
  • Si una métrica falla por separado, vuelve como objeto de error y las demás vienen con status 200.
  • Cada llamada lee una conexión (customer_integration) y exige el x-customer-token del cliente.

Campos principales

CampoTipoObligatorioDescripción
customer_integrationstringSíUUID de la conexión del cliente de donde se leen las métricas. Una por llamada.
startstringSíInicio del período (YYYY-MM-DD). Debe ser menor o igual a end.
endstringSíFin del período (YYYY-MM-DD).
metrics.reference_keystringSíMétrica del catálogo cuyo component es datatable_v1 o datagrid_v1, como fb_ads:insights_by_campaign.
metrics.componentstringSídatatable_v1 para datos tabulares; datagrid_v1 para grillas, como stories de Instagram.
metrics.metricsarraySíLas columnas pedidas (por ejemplo spend, reach, ctr).
metrics.dimensionsarrayNoEl desglose del resultado. Cópialo del ítem del catálogo.

Para quién

  • Tabla de campañas en tu producto

    Lista las campañas del cliente con gasto, alcance y CTR dentro de tu interfaz, sin integrar Meta Ads.

  • Informes de desempeño de medios pagos

    Arma el ranking de campañas de cada cliente para el informe mensual de la agencia.

  • Agentes que analizan campañas

    Un agente lee la tabla y señala las campañas con peor costo por resultado.

Preguntas frecuentes

¿Cuál es la diferencia entre datatable_v1 y datagrid_v1?

datatable_v1 entrega datos tabulares; datagrid_v1 entrega una grilla, como la de stories de Instagram. El catálogo de cada plataforma muestra qué component usa cada métrica.

¿Cómo desgloso el resultado por campaña?

Usa fb_ads:insights_by_campaign, el ítem del catálogo de Meta Ads que ya viene con la dimensión de campaña, y copia sus metrics y dimensions.

¿Puedo paginar la tabla?

La spec no describe paginación ni orden para las tablas, así que no se documenta aquí. El recorte se hace con el período, las métricas y las dimensiones.

Relacionadas

Ver todo lo que puedes hacer con Metrics

Mira Connect aplicado a tu producto.

Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.