Nutzungsanalytik und Kontingente

Die Nutzungsanalytik-Endpunkte bieten Ihnen vollständige Transparenz über Ihre API-Verbrauchsmuster. Verwenden Sie diese Endpunkte, um den Kontingentverbrauch zu verfolgen, Nutzungstrends zu überwachen, Großverbraucher zu identifizieren und API-Aufrufe für die Compliance zu auditieren.

Alle Nutzungsendpunkte sind auf Ihren Mandanten beschränkt. Sie können nur Ihre eigenen Daten einsehen.

Erforderlicher Bereich: usage:read

Nutzungszusammenfassung

Erhalten Sie eine aggregierte Ansicht Ihrer API-Nutzung über einen bestimmten Zeitraum.

Endpunkt

GET /api/v1/usage/summary

Abfrageparameter

Parameter	Typ	Standard	Beschreibung
period	string	30d	Zeitraum: 24h, 7d, 30d, 90d

Anfrage

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

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

Nutzungsverlauf

Sehen Sie chronologische Nutzungsdaten, aufgeschlüsselt nach Stunde oder Tag.

Endpunkt

GET /api/v1/usage/history

Abfrageparameter

Parameter	Typ	Standard	Beschreibung
period	string	7d	Zeitraum: 24h, 7d, 30d, 90d
granularity	string	auto	hourly oder daily (automatische Auswahl nach Zeitraum)

Automatische Granularität

Zeitraum	Standard-Granularität
24h	hourly
7d	daily
30d	daily
90d	daily

Nutzung nach Scan-Typ

Aufschlüsselung Ihrer API-Nutzung nach Scan-Engine.

Endpunkt

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

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

Nutzung nach API-Schlüssel

Sehen Sie, welche API-Schlüssel die meiste Nutzung erzeugen.

Endpunkt

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

API-Aufrufprotokolle

Rufen Sie ein detailliertes Audit-Protokoll einzelner API-Aufrufe ab.

Endpunkt

GET /api/v1/usage/call-logs

Abfrageparameter

Parameter	Typ	Standard	Beschreibung
period	string	24h	Zeitraum: 24h, 7d, 30d
page	integer	1	Seitennummer
limit	integer	50	Ergebnisse pro Seite (max.: 100)

Kontingentzystem

Ihr Abonnementplan definiert die Anzahl der kontingentverbrauchenden API-Aufrufe, die Sie pro Abrechnungszeitraum (Kalendermonat) durchführen können.

Was Kontingent verbraucht

Aktion	Verbraucht Kontingent
POST /scans (Erfolg, 201)	Ja
POST /scan-templates/:id/launch (Erfolg, 201)	Ja
GET /scans (Scans auflisten)	Nein
GET /scans/:id (Status prüfen)	Nein
GET /scans/:id/results (Ergebnisse abrufen)	Nein
POST /scans/:id/cancel	Nein
Jede fehlgeschlagene Anfrage (4xx, 5xx)	Nein
Webhook-/Vorlagen-/Nutzungsendpunkte	Nein

Regel: Nur erfolgreiche Scan-Erstellungsaufrufe (HTTP 201) verbrauchen Kontingent.

Kontingent überschritten

{
  "success": false,
  "error": "Monatliches Scan-Kontingent überschritten. Aktuelle Nutzung: 500/500. Upgraden Sie Ihren Plan oder warten Sie auf den nächsten Abrechnungszeitraum.",
  "code": "QUOTA_EXCEEDED"
}

HTTP-Status: 429 Too Many Requests

Kontingent-Zurücksetzung

Kontingente werden am Anfang jedes Kalendermonats (Mitternacht UTC am 1.) zurückgesetzt.

Zeitraumfilterung

Alle Nutzungsendpunkte unterstützen den period-Parameter:

Zeitraum	Bereich
24h	Letzte 24 Stunden
7d	Letzte 7 Tage
30d	Letzte 30 Tage
90d	Letzte 90 Tage

---

Nächste Schritte:

• Fehlerreferenz →
• Code-Beispiele →
• Authentifizierung →