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 un
mensaje genérico que pide hablar con el 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.