Métricas de la API
Endpoints de la API del panel para consultar el uso que hace una aplicación externa de la API: peticiones, latencia, errores, endpoints, avisos e IA.
Actualizado el . 3 min de lectura
Incluido en todos los planes. Ver precios
Con estos endpoints consultas cómo usa la API una de tus aplicaciones externas: cuántas peticiones hace, cuánto tardan, qué errores devuelven, qué endpoints usa más, cómo van sus avisos y cuánto consume de IA. Son los datos de la pestaña Métricas de la ficha de la aplicación, en Gestión de proyectos › Aplicaciones externas, necesitas entrar con tu cuenta.
Autenticación, plan y permisos
Son endpoints de administración de la API del panel
(/api/integrations/apps/...): se llaman con la sesión de un
usuario (Authorization: Bearer <token>), exigen el permiso
EXTERNAL_APPS_VIEW y que el plan de tu organización incluya el
aplicativo Integraciones.
Aquí no vale la cabecera X-Api-Key
X-Api-Key es de la API externa (/api/external/v1/...). Una llamada a
/api/integrations/apps/... con X-Api-Key y sin
Authorization: Bearer responde 401. Si lo que quieres es que la
propia aplicación consulte su uso de IA, usa la
analítica de IA.
Endpoints
/api/integrations/apps/:id/metricsResumen de uso de la API de la aplicación en el periodo. Permiso: EXTERNAL_APPS_VIEW.
/api/integrations/apps/:id/metrics/requestsPeticiones a lo largo del periodo. Permiso: EXTERNAL_APPS_VIEW.
/api/integrations/apps/:id/metrics/latencyLatencia a lo largo del periodo (p50, p95, p99 y media). Permiso: EXTERNAL_APPS_VIEW.
/api/integrations/apps/:id/metrics/errorsErrores agrupados por código de estado. Permiso: EXTERNAL_APPS_VIEW.
/api/integrations/apps/:id/metrics/endpointsEndpoints más usados, con su latencia media y su tasa de error. Permiso: EXTERNAL_APPS_VIEW.
/api/integrations/apps/:id/metrics/webhooksEntregas de avisos correctas y fallidas, en total y por evento. Permiso: EXTERNAL_APPS_VIEW.
/api/integrations/apps/:id/metrics/aiUso de IA de la aplicación, siempre dentro de tu organización. Permiso: EXTERNAL_APPS_VIEW.
Parámetros
- idpathobligatorio
- Identificador de la aplicación externa.
- periodquery
- Ventana de tiempo: 24h, 7d, 30d o 90d. Por defecto, 24h. No aplica a /metrics/ai.
- startDate / endDatequery
- Solo en /metrics/ai: inicio y fin del periodo, en formato ISO 8601.
- Authorizationheaderobligatorio
- Bearer con el token de sesión del usuario.
Respuestas
Resumen (/metrics)
- totalRequestsnumberobligatorio
- Total de peticiones en el periodo.
- avgResponseTimeMsnumberobligatorio
- Tiempo de respuesta medio, en milisegundos.
- errorRatenumberobligatorio
- Porcentaje de peticiones con error.
- rateLimitHitsnumberobligatorio
- Veces que se alcanzó el límite de peticiones.
- trendsobjectobligatorio
- Variación frente al periodo anterior: requests, responseTime, errorRate y rateLimitHits.
- periodstringobligatorio
- Periodo consultado.
Series y desgloses
| Endpoint | Cada elemento lleva |
|---|---|
/metrics/requests | timestamp, count |
/metrics/latency | timestamp, p50, p95, p99, avg |
/metrics/errors | statusCode, errorType, count |
/metrics/endpoints | endpoint, method, count, avgLatencyMs, errorRate |
/metrics/webhooks devuelve un objeto con total, success, failed,
successRate, period y byEvent, una lista con esas mismas cifras
para cada evento. /metrics/ai devuelve el mismo resumen que la
analítica de IA de la
API externa. Ninguna de estas respuestas va paginada.
Ejemplos
curl -X GET "https://os.utilia.ai/api/integrations/apps/$APP_ID/metrics?period=24h" \
-H 'Authorization: Bearer '"$TOKEN"Errores frecuentes
401: falta el token de sesión enAuthorization, ha caducado o no es válido.403: falta el permisoEXTERNAL_APPS_VIEWo el plan no incluye Integraciones.404: la aplicación indicada en:idno existe en tu organización.
Siguiente paso
Todo lo que se puede hacer con una aplicación desde el panel (crearla, rotar su clave, configurar sus avisos o activar OAuth) está en Panel de aplicaciones externas y, endpoint a endpoint, en la API de administración de integraciones.