Metrics

Comparar períodos de métricas con la API

En POST /metrics/get-data envías el período principal y, si quieres, un período de comparación. La respuesta ya trae el valor actual y el anterior, así tu producto muestra la variación sin una segunda llamada. Sin OAuth, sin revisión de app, sin renovar tokens.

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",
  "comparison_start": "2026-07-01",
  "comparison_end": "2026-07-31",
  "metrics": [
    {
      "id": "f35a44ce-dac5-4188-aace-5c44a8952176",
      "reference_key": "fb_ads:spend",
      "component": "number_v1",
      "metrics": [
        "spend"
      ]
    }
  ]
}

Qué puedes hacer

  • Comparar el mes actual con el anterior, o cualquier par de períodos, en una sola llamada.
  • Pedir varias métricas a la vez, cada una con su component.
  • Ajustar la zona horaria con client_timezone para que los días cierren como espera tu cliente.
  • Usar la versión asíncrona (get-data-async) con los mismos campos de comparación en períodos largos.

Reglas y límites

  • comparison_start solo se considera si también se envía comparison_end.
  • En el ejemplo de la spec, un number_v1 vuelve con value (período actual) y previous_value (período de comparación).
  • El resultado viene en el objeto data, con el id (UUID) de cada métrica como clave.
  • Si una métrica falla por separado, vuelve como objeto de error (por ejemplo no_data_in_period) y las demás vienen normalmente, 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).
comparison_startstringNoInicio del período de comparación (YYYY-MM-DD). Solo se considera si también se envía comparison_end.
comparison_endstringNoFin del período de comparación (YYYY-MM-DD).
client_timezonestringNoZona horaria, como America/Sao_Paulo (por defecto).
metricsarraySíLista de métricas pedidas, al menos una. Cada ítem trae id, reference_key, component y metrics.

Para quién

  • Tarjetas de variación en dashboards

    Tu panel muestra gasto o seguidores con la flecha de alza o caída sobre el período anterior, a partir de una sola respuesta.

  • Informes mensuales de agencia

    Genera el comparativo mes a mes de cada cliente sin calcular la diferencia de tu lado.

  • Agentes que explican variaciones

    Un agente lee actual y anterior y escribe el análisis de lo que cambió, con los números que vienen de la API.

Preguntas frecuentes

¿Cómo pido la comparación?

Envía comparison_start y comparison_end junto con start y end en POST /metrics/get-data. Si envías solo uno de los dos, la comparación no se considera.

¿El período de comparación debe tener el mismo tamaño?

La spec no lo exige: tú eliges las dos fechas. Para una comparación justa, usa períodos del mismo tamaño.

¿Funciona con todas las métricas?

Depende de la métrica y del component. El ejemplo de la spec muestra number_v1 volviendo con value y previous_value. Prueba la métrica que necesitas del catálogo GET /metrics/{integration_slug}.

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.