Resumen

API REST de solo lectura para extraer metricas de campanas, push, codigos, puntos, ranking, tiers, journeys y marketplace.

La API de Metricas permite a sistemas externos (BI, data warehouses, dashboards propios) extraer de forma programatica las metricas de tu organizacion. Es de solo lectura y vive bajo el namespace /api/v1/metrics/**.

Base URL

https://southgames.ai/api/v1/metrics

Autenticacion y permisos

Como el resto de la API, requiere los headers Authorization: Bearer <api_key> y X-Org-Id. Ademas, la API key debe tener el scope metrics:read (o ser una key de acceso completo).

Crea una key de solo metricas en Configuracion > Desarrollador > API Keys, eligiendo el permiso "Solo metricas". Una key de metricas no puede llamar endpoints de escritura (p. ej. /points/spend, /games/play).

Ver Autenticacion para mas detalles sobre keys y scopes.

Rate limiting

Cada API key tiene un limite de 120 solicitudes por minuto (ventana fija). Las respuestas exitosas incluyen headers informativos:

Al superar el limite la API responde 429 con codigo RATE_LIMITED.

Rango de fechas

La mayoria de los endpoints aceptan un rango de fechas comun:

El rango maximo es de 366 dias. Un rango invalido (from posterior a to, fecha no parseable, tz invalida o rango excedido) devuelve 400 con codigo VALIDATION_ERROR.

Frescura de los datos

Hay dos clases de endpoints:

Formato de respuesta

Las respuestas exitosas devuelven el objeto de datos directamente (sin envoltorio success), con HTTP 200 y los headers X-RateLimit-*:

{
  "range": { "from": "2026-05-17T00:00:00.000Z", "to": "2026-06-16T00:00:00.000Z" },
  "totals": { "sessions": 12840, "winRate": 40 }
}

Los errores devuelven { error, code } con el HTTP correspondiente:

{ "error": "Limite de solicitudes excedido. Intenta de nuevo mas tarde.", "code": "RATE_LIMITED" }

Codigos de error

Tambien aplican los errores de autenticacion comunes (MISSING_API_KEY, INVALID_API_KEY, etc.).

Endpoints