Analíticas de uso y cuotas
Los endpoints de analíticas de uso le ofrecen visibilidad completa sobre sus patrones de consumo API. Use estos endpoints para rastrear el consumo de cuotas, monitorear tendencias de uso, identificar los mayores consumidores y auditar llamadas API para cumplimiento.
Todos los endpoints de uso están limitados a su tenant. Solo puede ver sus propios datos.
Alcance requerido: usage:read
Resumen de uso
Obtenga una vista agregada de su uso API durante un período determinado.
Endpoint
GET /api/v1/usage/summary
Parámetros de consulta
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
period | string | 30d | Período: 24h, 7d, 30d, 90d |
Solicitud
curl -X GET "https://api.cert-ix.com/scan-api/api/v1/usage/summary?period=30d" \
-H "X-API-Key: $CERTIX_API_KEY"
Respuesta (200 OK)
{
"success": true,
"data": {
"tenantId": "7b5b0610-2947-412f-a869-4683da321fcf",
"period": {
"start": "2026-02-04T00:00:00Z",
"end": "2026-03-06T23:59:59Z"
},
"totalCalls": 4827,
"successCalls": 4512,
"errorCalls": 315,
"avgDurationMs": 245,
"maxDurationMs": 12450,
"totalScans": 892,
"distinctScanTypes": 5,
"scanTypesUsed": ["nmap", "zap", "nuclei", "trivy", "sentinel"],
"quotaConsumedCalls": 892
}
}
Historial de uso
Consulte datos de uso cronológicos, desglosados por hora o por día.
Endpoint
GET /api/v1/usage/history
Parámetros de consulta
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
period | string | 7d | Período: 24h, 7d, 30d, 90d |
granularity | string | auto | hourly o daily (selección automática según el período) |
Granularidad automática
| Período | Granularidad predeterminada |
|---|---|
24h | hourly |
7d | daily |
30d | daily |
90d | daily |
Uso por tipo de análisis
Desglose de su uso API por motor de análisis.
Endpoint
GET /api/v1/usage/by-scan-type
Respuesta (200 OK)
{
"success": true,
"data": {
"scanTypes": [
{
"scanType": "nmap",
"totalScans": 342,
"successScans": 330,
"failedScans": 12,
"avgDurationMs": 85000,
"percentOfTotal": 38.3
},
{
"scanType": "nuclei",
"totalScans": 278,
"successScans": 271,
"failedScans": 7,
"avgDurationMs": 120000,
"percentOfTotal": 31.2
}
]
}
}
Uso por clave API
Consulte qué claves API generan más uso.
Endpoint
GET /api/v1/usage/by-api-key
Respuesta (200 OK)
{
"success": true,
"data": {
"apiKeys": [
{
"keyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"keyName": "Pipeline CI/CD - Producción",
"keyPrefix": "cix_sk_001e3c",
"totalCalls": 3241,
"successCalls": 3100,
"errorCalls": 141,
"lastUsedAt": "2026-03-06T09:45:12Z"
}
]
}
}
Registros de llamadas API
Obtenga un registro de auditoría detallado de las llamadas API individuales.
Endpoint
GET /api/v1/usage/call-logs
Parámetros de consulta
| Parámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
period | string | 24h | Período: 24h, 7d, 30d |
page | integer | 1 | Número de página |
limit | integer | 50 | Resultados por página (máx.: 100) |
Sistema de cuotas
Su plan de suscripción define el número de llamadas API que consumen cuota por período de facturación (mes calendario).
Qué consume cuota
| Acción | Consume cuota |
|---|---|
POST /scans (éxito, 201) | Sí |
POST /scan-templates/:id/launch (éxito, 201) | Sí |
GET /scans (listar análisis) | No |
GET /scans/:id (verificar estado) | No |
GET /scans/:id/results (obtener resultados) | No |
POST /scans/:id/cancel | No |
| Cualquier solicitud fallida (4xx, 5xx) | No |
| Endpoints de webhook/plantilla/uso | No |
Regla: Solo las llamadas exitosas de creación de análisis (HTTP 201) consumen cuota.
Cuota excedida
{
"success": false,
"error": "Cuota mensual de análisis excedida. Uso actual: 500/500. Actualice su plan o espere al siguiente período de facturación.",
"code": "QUOTA_EXCEEDED"
}
Estado HTTP: 429 Too Many Requests
Reinicio de cuotas
Las cuotas se reinician al inicio de cada mes calendario (medianoche UTC el día 1).
Filtrado por período
Todos los endpoints de uso soportan el parámetro period:
| Período | Rango |
|---|---|
24h | Últimas 24 horas |
7d | Últimos 7 días |
30d | Últimos 30 d ías |
90d | Últimos 90 días |
Próximos pasos: