Metrics
Recibir métricas por webhook con la API
Con POST /metrics/get-data-async pides las métricas y la API responde al instante. El resultado llega después, en un POST a tu metrics_webhook_url. Es el camino recomendado para períodos largos, y no necesitas OAuth, revisión de app ni renovación de tokens.
La llamada
POST /api/metrics/get-data-async
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
{
"metrics_webhook_url": "https://sua-aplicacao.com/webhooks/metricas",
"customer_integration": "<connection uuid>",
"start": "2026-08-01",
"end": "2026-08-31",
"metrics": [
{
"id": "f35a44ce-dac5-4188-aace-5c44a8952176",
"reference_key": "ig:story_replies",
"component": "number_v1",
"metrics": [
"replies"
]
}
]
}Qué puedes hacer
- Pedir varias métricas de una conexión en una sola llamada, cada una con su component.
- Recibir el resultado en un endpoint tuyo, sin mantener la solicitud abierta mientras se recolectan los datos.
- Usar los mismos reference_keys del catálogo GET /metrics/{integration_slug} que la versión síncrona.
- Pedir también un período de comparación con comparison_start y comparison_end.
Reglas y límites
- La respuesta inmediata es 200 con success: true y el mensaje Metrics will be sent to your webhook.
- El cuerpo entregado al webhook es el mapa de métricas en la raíz, sin el envoltorio data de la versión síncrona. Cada clave es el id (UUID) que enviaste.
- metrics_webhook_url debe ser http o https y apuntar a una dirección pública: IP privadas, loopback y link-local devuelven 422.
- Cada llamada lee una sola conexión (customer_integration) y exige el x-customer-token del cliente dueño de ella.
- En el período de prueba, start puede retroceder como máximo 62 días y metrics acepta hasta 15 ítems (trial_history_limit y trial_metrics_limit).
Campos principales
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| metrics_webhook_url | string | Sí | URL http o https pública que recibe las métricas. Se rechazan IP privadas, loopback y link-local. |
| 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 | array | Sí | Lista de métricas pedidas, al menos una. Cada ítem trae id, reference_key, component y metrics. |
| metrics.reference_key | string | Sí | Identificador de la métrica, del catálogo GET /metrics/{integration_slug}. |
Para quién
Informes mensuales en lote
Tu SaaS lanza la recolección de todos los clientes por la noche y procesa cada resultado cuando llega al webhook, sin hilos bloqueados esperando.
Dashboards de agencia
Pide el año completo de una cuenta al cargar el panel y actualiza la pantalla cuando el webhook entregue los datos.
Agentes de IA
Un agente pide la recolección, sigue con otras tareas y retoma el análisis cuando el webhook trae las métricas.
Preguntas frecuentes
¿Cuál es la diferencia entre get-data y get-data-async?
get-data mantiene la solicitud abierta y responde con los datos dentro de un objeto data. get-data-async responde al instante y entrega las métricas en un POST a tu metrics_webhook_url, sin el envoltorio data. Para períodos largos, usa la asíncrona.
¿Puedo apuntar el webhook a localhost?
No. La URL se valida y debe ser pública: IP privadas, loopback y link-local se rechazan con 422. Para probar en local, usa un túnel con URL pública.
¿Puedo recolectar de varias cuentas en una sola llamada?
No. Cada llamada lee una conexión, indicada en customer_integration. Para varias cuentas, haz una llamada por conexión.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
