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

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 cuyo catálogo indica chart_v1, como ig:followers_gender.
metrics.componentstringSíUsa chart_v1 para recibir los datos en formato de gráfico.
metrics.metricsarraySíLos valores pedidos dentro de la métrica. Cópialos del ítem del catálogo.
metrics.idstringSí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.

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.