# 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.

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](https://os.utilia.ai/docs/developers/api/ticket-ai-suggestions)):
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](https://os.utilia.ai/docs/developers/api/scopes).

## Endpoints

**`GET /api/external/v1/ai-analytics/overview`**

Resumen del uso de IA de la aplicación en el periodo. Permiso: analytics:ai:read.

**`GET /api/external/v1/ai-analytics/trends`**

Evolución diaria del uso de IA de la aplicación. Permiso: analytics:ai:read.

Los dos admiten los mismos parámetros de consulta:

| Nombre | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `startDate` | `string` | No | Inicio del periodo, en formato ISO 8601. |
| `endDate` | `string` | No | Fin del periodo, en formato ISO 8601. |

## Respuesta del resumen

| Nombre | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `totalRequests` | `number` | Sí | Peticiones de IA en el periodo. |
| `successfulRequests / failedRequests` | `number` | Sí | Peticiones correctas y fallidas. |
| `successRate` | `number` | Sí | Porcentaje de peticiones correctas (de 0 a 100). |
| `totalCostUSD / avgCostPerRequest` | `number` | Sí | Coste total y coste medio por petición, en dólares. |
| `totalTokensInput / totalTokensOutput` | `number` | Sí | Tokens de entrada y de salida. |
| `suggestionsGenerated` | `number` | Sí | Sugerencias generadas. |
| `suggestionsAccepted / Modified / Rejected / Ignored` | `number` | Sí | Sugerencias aceptadas, cambiadas, descartadas e ignoradas, según lo registrado con /tickets/ai-track-action. |
| `acceptanceRate` | `number` | Sí | Porcentaje de sugerencias aceptadas (de 0 a 100). |
| `avgProcessingTimeMs` | `number` | Sí | Tiempo medio de proceso, en milisegundos. |
| `avgTimeToDecisionMs` | `number` | No | Tiempo medio hasta que el usuario decide, en milisegundos. |
| `requestsChange, successRateChange, costChange, acceptanceRateChange` | `number` | No | Variación frente al periodo anterior. |
| `sourceBreakdown` | `array` | No | 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

```bash
curl -X GET 'https://os.utilia.ai/api/external/v1/ai-analytics/overview' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: utl_xxx'
```

### fetch

```javascript
const res = await fetch('https://os.utilia.ai/api/external/v1/ai-analytics/overview', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'utl_xxx',
    'x-request-id': 'req-demo-001',
  },
});
const data = await res.json();
```

### axios

```javascript
const { data } = await axios({
  method: 'get',
  url: 'https://os.utilia.ai/api/external/v1/ai-analytics/overview',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'utl_xxx',
    'x-request-id': 'req-demo-001',
  },
});
```

### Python

```python
import requests
resp = requests.request(
  'GET',
  'https://os.utilia.ai/api/external/v1/ai-analytics/overview',
  headers={
    'Content-Type': 'application/json',
    'X-Api-Key': 'utl_xxx',
    'x-request-id': 'req-demo-001',
  },
  timeout=30,
)
print(resp.json())
```

## 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 permiso `analytics: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 cabecera `Retry-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.