Analítica de IA
Consulta desde tu aplicación el resumen y la evolución diaria de su propio uso de IA con /external/v1/ai-analytics y el permiso analytics:ai:read.
Actualizado el . 3 min de lectura
Incluido en todos los planes. Ver precios
Con /external/v1/ai-analytics tu aplicación consulta cifras de su
propio uso de IA en UTILIA OS (por ejemplo, el de las
sugerencias con IA en tickets):
peticiones, coste, tokens y qué hicieron los usuarios con las
sugerencias. Solo ve sus propios datos, nunca los de otras aplicaciones.
Autenticación, plan y permisos
Todas las peticiones llevan la clave de API de la aplicación:
X-Api-Key: <api_key_de_la_app>
El plan de tu organización tiene que incluir el aplicativo Integraciones.
| Endpoint | Permiso de la API (scope) |
|---|---|
GET /external/v1/ai-analytics/overview | analytics:ai:read |
GET /external/v1/ai-analytics/trends | analytics:ai:read |
Sin el permiso, los endpoints responden 403 INSUFFICIENT_SCOPE con el permiso que falta en
requiredScopes; lo concede un administrador de la organización. Se exige desde la primera llamada, sin periodo de gracia.
El catálogo completo está en Permisos de la API.
Endpoints
/api/external/v1/ai-analytics/overviewResumen del uso de IA de la aplicación en el periodo. Permiso: analytics:ai:read.
/api/external/v1/ai-analytics/trendsEvolución diaria del uso de IA de la aplicación. Permiso: analytics:ai:read.
Los dos admiten los mismos parámetros de consulta:
- startDatestring
- Inicio del periodo, en formato ISO 8601.
- endDatestring
- Fin del periodo, en formato ISO 8601.
Respuesta del resumen
- totalRequestsnumberobligatorio
- Peticiones de IA en el periodo.
- successfulRequests / failedRequestsnumberobligatorio
- Peticiones correctas y fallidas.
- successRatenumberobligatorio
- Porcentaje de peticiones correctas (de 0 a 100).
- totalCostUSD / avgCostPerRequestnumberobligatorio
- Coste total y coste medio por petición, en dólares.
- totalTokensInput / totalTokensOutputnumberobligatorio
- Tokens de entrada y de salida.
- suggestionsGeneratednumberobligatorio
- Sugerencias generadas.
- suggestionsAccepted / Modified / Rejected / Ignorednumberobligatorio
- Sugerencias aceptadas, cambiadas, descartadas e ignoradas, según lo registrado con /tickets/ai-track-action.
- acceptanceRatenumberobligatorio
- Porcentaje de sugerencias aceptadas (de 0 a 100).
- avgProcessingTimeMsnumberobligatorio
- Tiempo medio de proceso, en milisegundos.
- avgTimeToDecisionMsnumber
- Tiempo medio hasta que el usuario decide, en milisegundos.
- requestsChange, successRateChange, costChange, acceptanceRateChangenumber
- Variación frente al periodo anterior.
- sourceBreakdownarray
- Desglose por origen (por ejemplo, SDK o widget).
La respuesta de trends es una lista con un punto por día: date,
requests, acceptanceRate y costUSD.
Ejemplos
curl -X GET 'https://os.utilia.ai/api/external/v1/ai-analytics/overview' \
-H 'Content-Type: application/json' \
-H 'X-Api-Key: utl_xxx'Errores frecuentes
400: parámetros de consulta no válidos.401: falta la clave de API, no es válida o no es de una aplicación externa.403: falta el permisoanalytics:ai:read, la aplicación está desactivada, el origen no está permitido (CORS) o el plan no incluye Integraciones.429: se ha superado el límite por hora de la clave. La respuesta trae la cabeceraRetry-After.
Envía x-request-id en cada petición para poder seguirla en los registros.
Hasta el 1 de julio de 2026 estos endpoints devolvían todo a cero por un fallo interno, aunque la aplicación tuviera uso real de IA. Está corregido sin cambiar el contrato: si tu integración trataba los ceros como «sin datos», ahora recibirá las cifras reales.