Metrics
Obtener datos de gráficos de métricas con la API
El component define el formato del resultado. Con chart_v1 en POST /metrics/get-data, la métrica vuelve como datos de gráfico (línea, torta, barras) que tu front-end dibuja con la biblioteca que quieras. Sin recolectar ni agregar por plataforma.
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": "f35a44ce-dac5-4188-aace-5c44a8952176",
"reference_key": "ig:followers_gender",
"component": "chart_v1",
"metrics": [
"followers"
],
"dimensions": [
"gender"
]
}
]
}Qué puedes hacer
- Pedir métricas en formato de gráfico con component chart_v1, junto a number_v1 y tablas en la misma llamada.
- Descubrir qué métricas son gráficos en el catálogo GET /metrics/{integration_slug}, que trae el component por defecto de cada una.
- Combinar un gráfico con un período de comparación (comparison_start y comparison_end).
- Usar la versión asíncrona (get-data-async) para gráficos de períodos largos.
Reglas y límites
- Copia el ítem del catálogo en metrics[]: cada ítem de data ya es un ítem válido de la solicitud.
- El formato del resultado depende del component pedido; el payload es abierto, así que lee el resultado de cada métrica por la clave id.
- Si una métrica falla por separado, vuelve como objeto de error (invalid_metrics_combination, no_data_in_period, internal_error o expired_token) y las demás vienen con status 200.
- Cada llamada lee una conexión (customer_integration) y exige el x-customer-token del cliente.
- En el período de prueba, start retrocede como máximo 62 días y metrics acepta hasta 15 ítems.
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 cuyo catálogo indica chart_v1, como ig:followers_gender. |
| metrics.component | string | Sí | Usa chart_v1 para recibir los datos en formato de gráfico. |
| metrics.metrics | array | Sí | Los valores pedidos dentro de la métrica. Cópialos del ítem del catálogo. |
| metrics.id | string | Sí | UUID generado por ti; es la clave del resultado en la respuesta. |
Para quién
Paneles de desempeño en tu SaaS
Muestra la evolución de alcance o gasto en gráficos de línea dentro de tu producto, con datos de la cuenta conectada del cliente.
Informes de agencia
Arma páginas de informe con gráficos por plataforma sin integrar la API de cada red social.
Agentes de IA con contexto visual
Un agente busca la serie de datos de un gráfico y describe la tendencia al usuario.
Preguntas frecuentes
¿Cómo sé si una métrica viene como gráfico?
En el catálogo GET /metrics/{integration_slug}, cada ítem trae su component por defecto. Las que traen chart_v1 devuelven datos de gráfico.
¿La API dibuja el gráfico?
No. Devuelve los datos en el formato chart_v1; el dibujo queda a cargo de tu front-end.
¿Puedo mezclar gráficos y números en una llamada?
Sí. Cada ítem de metrics[] tiene su component, y cada resultado vuelve bajo el id del ítem.
Mira Connect aplicado a tu producto.
Pruébalo durante 15 días sin tarjeta, o cuéntale tu caso a nuestro equipo.
