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
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| customer_integration | string | Sí | UUID de la conexión del cliente de donde se leen las métricas. Una por llamada. |
| start | string | Sí | Inicio del período (YYYY-MM-DD). Debe ser menor o igual a end. |
| end | string | Sí | Fin del período (YYYY-MM-DD). |
| metrics.reference_key | string | Sí | Métrica del catálogo cuyo component es datatable_v1 o datagrid_v1, como fb_ads:insights_by_campaign. |
| metrics.component | string | Sí | datatable_v1 para datos tabulares; datagrid_v1 para grillas, como stories de Instagram. |
| metrics.metrics | array | Sí | Las columnas pedidas (por ejemplo spend, reach, ctr). |
| metrics.dimensions | array | No | El 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.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
