Analytique d'utilisation et quotas

Les endpoints d'analytique d'utilisation vous offrent une visibilité complète sur vos habitudes de consommation API. Utilisez ces endpoints pour suivre la consommation de quotas, surveiller les tendances d'utilisation, identifier les gros consommateurs et auditer les appels API pour la conformité.

Tous les endpoints d'utilisation sont limités à votre tenant. Vous ne pouvez voir que vos propres données.

Portée requise : usage:read

Résumé d'utilisation

Obtenez une vue agrégée de votre utilisation API sur une période donnée.

Endpoint

GET /api/v1/usage/summary

Paramètres de requête

Paramètre	Type	Défaut	Description
period	string	30d	Période : 24h, 7d, 30d, 90d

Requête

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/usage/summary?period=30d" \
  -H "X-API-Key: $CERTIX_API_KEY"

Réponse (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
  }
}

Champs de la réponse

Champ	Description
totalCalls	Nombre total d'appels API effectués
successCalls	Appels ayant retourné un code 2xx
errorCalls	Appels ayant retourné un code 4xx ou 5xx
avgDurationMs	Temps de réponse moyen en millisecondes
totalScans	Nombre total d'analyses soumises
distinctScanTypes	Nombre de moteurs différents utilisés
quotaConsumedCalls	Nombre d'appels ayant consommé du quota

Comptage des quotas

Tous les appels API ne consomment pas de quota. Seules les opérations d'analyse réussies (réponses 2xx) comptent dans le quota de votre plan.

Historique d'utilisation

Consultez les données d'utilisation chronologiques, ventilées par heure ou par jour.

Endpoint

GET /api/v1/usage/history

Paramètres de requête

Paramètre	Type	Défaut	Description
period	string	7d	Période : 24h, 7d, 30d, 90d
granularity	string	auto	hourly ou daily (sélection automatique selon la période)

Requête

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/usage/history?period=7d" \
  -H "X-API-Key: $CERTIX_API_KEY"

Réponse (200 OK)

{
  "success": true,
  "data": {
    "granularity": "daily",
    "entries": [
      {
        "timestamp": "2026-02-27T00:00:00Z",
        "totalCalls": 687,
        "successCalls": 645,
        "errorCalls": 42,
        "avgDurationMs": 198
      },
      {
        "timestamp": "2026-02-28T00:00:00Z",
        "totalCalls": 712,
        "successCalls": 690,
        "errorCalls": 22,
        "avgDurationMs": 234
      }
    ]
  }
}

Granularité automatique

Période	Granularité par défaut
24h	hourly
7d	daily
30d	daily
90d	daily

Utilisation par type d'analyse

Répartition de votre utilisation API par moteur d'analyse pour comprendre quels outils sont les plus utilisés.

Endpoint

GET /api/v1/usage/by-scan-type

Requête

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/usage/by-scan-type?period=30d" \
  -H "X-API-Key: $CERTIX_API_KEY"

Réponse (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
      }
    ]
  }
}

Utilisation par clé API

Consultez quelles clés API génèrent le plus d'utilisation. Utile pour les environnements multi-équipes ou lorsque vous avez des clés séparées pour différentes intégrations.

Endpoint

GET /api/v1/usage/by-api-key

Requête

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/usage/by-api-key?period=30d" \
  -H "X-API-Key: $CERTIX_API_KEY"

Réponse (200 OK)

{
  "success": true,
  "data": {
    "apiKeys": [
      {
        "keyId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "keyName": "Pipeline CI/CD - Production",
        "keyPrefix": "cix_sk_001e3c",
        "totalCalls": 3241,
        "successCalls": 3100,
        "errorCalls": 141,
        "lastUsedAt": "2026-03-06T09:45:12Z"
      }
    ]
  }
}

Journaux d'appels API

Récupérez un journal d'audit détaillé des appels API individuels pour la conformité et le débogage.

Endpoint

GET /api/v1/usage/call-logs

Paramètres de requête

Paramètre	Type	Défaut	Description
period	string	24h	Période : 24h, 7d, 30d
page	integer	1	Numéro de page
limit	integer	50	Résultats par page (max : 100)

Requête

curl -X GET "https://api.cert-ix.com/scan-api/api/v1/usage/call-logs?period=24h&page=1&limit=20" \
  -H "X-API-Key: $CERTIX_API_KEY"

Réponse (200 OK)

{
  "success": true,
  "data": {
    "logs": [
      {
        "id": "log-uuid-1",
        "method": "POST",
        "path": "/api/v1/scans",
        "statusCode": 201,
        "durationMs": 345,
        "scanType": "nmap",
        "target": "example.com",
        "quotaConsumed": true,
        "createdAt": "2026-03-06T10:00:00Z"
      }
    ],
    "total": 156,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

Conformité

Les journaux d'appels API incluent une chaîne de hachage d'intégrité pour la détection de falsification, conforme aux exigences ANSSI M25, NIS2 et DORA Art. 11.

Système de quotas

Votre plan d'abonnement définit le nombre d'appels API consommant du quota que vous pouvez effectuer par période de facturation (mois calendaire).

Ce qui consomme du quota

Action	Consomme du quota
POST /scans (succès, 201)	Oui
POST /scan-templates/:id/launch (succès, 201)	Oui
GET /scans (lister les analyses)	Non
GET /scans/:id (vérifier le statut)	Non
GET /scans/:id/results (récupérer les résultats)	Non
POST /scans/:id/cancel	Non
Toute requête échouée (4xx, 5xx)	Non
Endpoints webhook/modèle/utilisation	Non

Règle : Seuls les appels de création d'analyse réussis (HTTP 201) consomment du quota.

Quota dépassé

Lorsque votre quota mensuel est épuisé :

{
  "success": false,
  "error": "Quota mensuel d'analyses dépassé. Utilisation actuelle : 500/500. Mettez à niveau votre plan ou attendez la prochaine période de facturation.",
  "code": "QUOTA_EXCEEDED"
}

Statut HTTP : 429 Too Many Requests

Réinitialisation des quotas

Les quotas se réinitialisent au début de chaque mois calendaire (minuit UTC le 1er).

Filtrage par période

Tous les endpoints d'utilisation supportent le paramètre period pour un filtrage cohérent :

Période	Plage
24h	Dernières 24 heures
7d	7 derniers jours
30d	30 derniers jours
90d	90 derniers jours

---

Prochaines étapes :

• Référence des erreurs →
• Exemples de code →
• Authentification →