Analytics di utilizzo e quote

Gli endpoint di analytics di utilizzo vi offrono visibilità completa sui vostri pattern di consumo API. Usate questi endpoint per tracciare il consumo delle quote, monitorare le tendenze di utilizzo, identificare i maggiori consumatori e auditare le chiamate API per la conformità.

Tutti gli endpoint di utilizzo sono limitati al vostro tenant. Potete visualizzare solo i vostri dati.

Scope richiesto: usage:read

Riepilogo dell'utilizzo

Ottenete una vista aggregata del vostro utilizzo API durante un periodo determinato.

Endpoint

GET /api/v1/usage/summary

Parametri di query

Parametro	Tipo	Predefinito	Descrizione
period	string	30d	Periodo: 24h, 7d, 30d, 90d

Richiesta

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

Risposta (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
  }
}

Storico dell'utilizzo

Consultate dati di utilizzo cronologici, suddivisi per ora o per giorno.

Endpoint

GET /api/v1/usage/history

Parametri di query

Parametro	Tipo	Predefinito	Descrizione
period	string	7d	Periodo: 24h, 7d, 30d, 90d
granularity	string	auto	hourly o daily (selezione automatica in base al periodo)

Granularità automatica

Periodo	Granularità predefinita
24h	hourly
7d	daily
30d	daily
90d	daily

Utilizzo per tipo di scansione

Dettaglio del vostro utilizzo API per motore di scansione.

Endpoint

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

Risposta (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
      }
    ]
  }
}

Utilizzo per chiave API

Consultate quali chiavi API generano il maggior utilizzo.

Endpoint

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

Risposta (200 OK)

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

Log delle chiamate API

Ottenete un registro di audit dettagliato delle singole chiamate API.

Endpoint

GET /api/v1/usage/call-logs

Parametri di query

Parametro	Tipo	Predefinito	Descrizione
period	string	24h	Periodo: 24h, 7d, 30d
page	integer	1	Numero di pagina
limit	integer	50	Risultati per pagina (max.: 100)

Sistema di quote

Il vostro piano di abbonamento definisce il numero di chiamate API che consumano quota per periodo di fatturazione (mese di calendario).

Cosa consuma quota

Azione	Consuma quota
POST /scans (successo, 201)	Sì
POST /scan-templates/:id/launch (successo, 201)	Sì
GET /scans (elencare scansioni)	No
GET /scans/:id (verificare stato)	No
GET /scans/:id/results (ottenere risultati)	No
POST /scans/:id/cancel	No
Qualsiasi richiesta fallita (4xx, 5xx)	No
Endpoint webhook/template/utilizzo	No

Regola: Solo le chiamate di creazione scansione riuscite (HTTP 201) consumano quota.

Quota superata

{
  "success": false,
  "error": "Quota mensile di scansioni superata. Utilizzo attuale: 500/500. Aggiornate il vostro piano o attendete il prossimo periodo di fatturazione.",
  "code": "QUOTA_EXCEEDED"
}

Stato HTTP: 429 Too Many Requests

Reset delle quote

Le quote vengono resettate all'inizio di ogni mese di calendario (mezzanotte UTC il giorno 1).

Filtraggio per periodo

Tutti gli endpoint di utilizzo supportano il parametro period:

Periodo	Intervallo
24h	Ultime 24 ore
7d	Ultimi 7 giorni
30d	Ultimi 30 giorni
90d	Ultimi 90 giorni

---

Prossimi passi:

• Riferimento errori →
• Esempi di codice →
• Autenticazione →