> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Geschwindigkeits- und Anomaliebewertung

> Verfolgen Sie die Aktionshäufigkeit über rollierende Zeitfenster, erkennen Sie Geschwindigkeitsanomalien und nehmen Sie Risikosignale automatisch auf, wenn Schwellenwerte überschritten werden.

Die API zur Geschwindigkeits- und Anomaliebewertung verfolgt, wie häufig ein Subjekt eine bestimmte Aktion über mehrere gleitende Zeitfenster hinweg ausführt – 1 Minute, 5 Minuten, 1 Stunde und 24 Stunden. Wenn der gewichtete Geschwindigkeitswert einen Schwellenwert überschreitet, erstellt die Plattform automatisch ein [Risikosignal](https://docs.truthlocks.com/de/guides/risk-signals.md), das die Anomalieerkennung direkt mit der Anti-Betrugs-Identitäts-Firewall-Pipeline verbindet.

> [!NOTE]
>
> Die Geschwindigkeitsbewertung ist Teil der [Anti-Fraud Identity Firewall](https://docs.truthlocks.com/de/guides/risk-signals.md). Signale, die durch Geschwindigkeitsanomalien erzeugt werden, fließen in dieselbe Pipeline wie andere Betrugssignale, sodass Sie sie von der Konsolenseite **Risk & Fraud > Signals** oder dem [list signals endpoint](https://docs.truthlocks.com/de/api-reference/risk-signals/list.md) abfragen und überprüfen können.

## Funktionsweise

**1. Aktionen aufzeichnen**

Rufen Sie `POST /v1/risk/velocity/record` jedes Mal auf, wenn ein Subjekt eine verfolgte Aktion ausführt – Anmeldeversuche, API-Aufrufe, Transaktionsanfragen oder jede benutzerdefinierte Aktion.

**2. Tracking im rollierenden Fenster**

Die Plattform erhöht Zähler für das Subjekt und den Aktionstyp über vier rollierende Fenster (1 m, 5 m, 1 h, 24 h). Fenster werden automatisch zurückgesetzt, wenn sie ablaufen.

**3. Gewichtete Bewertung**

Ein Geschwindigkeitswert wird aus den Fensterzählungen berechnet. Kurze Fenster werden stärker gewichtet, um Bursts zu erkennen: 1 m × 30, 5 m × 20, 1 h × 10, 24 h × 5.

**4. Automatische Signalerfassung**

Wenn der Geschwindigkeitsscore 60 oder höher erreicht, nimmt die Plattform automatisch ein Risikosignal mit `signal_type: "velocity"` auf. Sie benötigen keinen separaten API-Aufruf.

**5. Überprüfen und antworten**

Fragen Sie Geschwindigkeitsfenster für ein Subjekt ab, listen Sie Anomalien mit hoher Geschwindigkeit in Ihrem Mandanten auf und überprüfen Sie Signale in der Konsole oder über die API.

## Voraussetzungen

* Ein aktiver Truthlocks-Mandant mit einem API-Schlüssel
* Aktionsereignisdaten aus Ihrer Anwendung (Anmeldeversuche, API-Aufrufe, Transaktionen oder jede wiederholbare Aktion)

## Eine Aktion aufzeichnen

Senden Sie eine `POST`-Anfrage an `/v1/risk/velocity/record` mit dem Betreff, dem Aktionstyp und optionalen Metadaten:

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/risk/velocity/record \
  -H "X-API-Key: tl_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user_abc123",
    "action_type": "login.failed",
    "ip_address": "198.51.100.42"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/velocity/record", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    subject_id: "user_abc123",
    action_type: "login.failed",
    ip_address: "198.51.100.42",
  }),
});
const result = await response.json();
```

```python Python theme={null}
import httpx

resp = httpx.post(
    "https://api.truthlocks.com/v1/risk/velocity/record",
    headers={"X-API-Key": "tl_live_..."},
    json={
        "subject_id": "user_abc123",
        "action_type": "login.failed",
        "ip_address": "198.51.100.42",
    },
)
result = resp.json()
```

Die Antwort gibt die aktuellen Fensterzählungen, den berechneten Geschwindigkeitsscore und an, ob ein Risikosignal automatisch aufgenommen wurde:

```json theme={null}
{
  "subject_id": "user_abc123",
  "action_type": "login.failed",
  "windows": {
    "1m": 3,
    "5m": 8,
    "1h": 15,
    "24h": 42
  },
  "velocity_score": 72,
  "signal_ingested": true,
  "signal_id": "a1b2c3d4-..."
}
```

## Bewertungsmodell

Der Geschwindigkeitsscore ist eine gewichtete Summe der Aktionszählungen über vier gleitende Fenster. Kurze Fenster haben ein höheres Gewicht, um die Erkennung von Bursts zu priorisieren:

| Fenster | Gewicht | Zweck |
| :- | :- | :- |
| 1 Minute | 30 | Erkennt schnelle Bursts (Credential Stuffing, automatisierte Angriffe) |
| 5 Minuten | 20 | Fängt anhaltenden kurzfristigen Missbrauch ab |
| 1 Stunde | 10 | Identifiziert mittelfristige Muster |
| 24 Stunden | 5 | Kennzeichnet anhaltende Anomalien über längere Zeiträume |

Der Endwert ist auf 100 begrenzt. Wenn der Wert **60 oder höher** erreicht, wird automatisch ein Risikosignal mit `signal_type: "velocity"` erfasst.

### Score-Interpretation

| Punktebereich | Interpretation | Beispiel |
| :- | :- | :- |
| 0–29 | Normal | Typische Benutzeraktivität |
| 30–59 | Erhöht | Überdurchschnittliche Häufigkeit, Überwachung wert |
| 60–79 | Hoch | Wahrscheinlich automatisiert oder missbräuchlich – Signal automatisch erfasst |
| 80–100 | Kritisch | Starke Anomalie – sofortige Untersuchung empfohlen |

## Geschwindigkeitsfenster abfragen

Rufen Sie die aktuellen Geschwindigkeitsfenster für ein bestimmtes Subjekt ab:

```bash cURL theme={null}
curl https://api.truthlocks.com/v1/risk/velocity/user_abc123 \
  -H "X-API-Key: tl_live_..."
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/risk/velocity/user_abc123", {
  headers: { "X-API-Key": "tl_live_..." },
});
const windows = await response.json();
```

```python Python theme={null}
import httpx

resp = httpx.get(
    "https://api.truthlocks.com/v1/risk/velocity/user_abc123",
    headers={"X-API-Key": "tl_live_..."},
)
windows = resp.json()
```

Die Antwort enthält alle verfolgten Aktionstypen für das Subjekt, mit Zählungen pro Fenster und dem berechneten Geschwindigkeitsscore für jeden:

```json theme={null}
{
  "subject_id": "user_abc123",
  "actions": [
    {
      "action_type": "login.failed",
      "windows": {
        "1m": 0,
        "5m": 2,
        "1h": 8,
        "24h": 23
      },
      "velocity_score": 45
    },
    {
      "action_type": "api.request",
      "windows": {
        "1m": 12,
        "5m": 45,
        "1h": 200,
        "24h": 800
      },
      "velocity_score": 87
    }
  ]
}
```

## Auflistung von Anomalien mit hoher Geschwindigkeit

Betreffs mit Geschwindigkeitswerten über einem Schwellenwert in Ihrem Mandanten abfragen:

```bash cURL theme={null}
curl "https://api.truthlocks.com/v1/risk/velocity?min_score=50&limit=25" \
  -H "X-API-Key: tl_live_..."
```

```javascript JavaScript theme={null}
const response = await fetch(
  "https://api.truthlocks.com/v1/risk/velocity?min_score=50&limit=25",
  { headers: { "X-API-Key": "tl_live_..." } }
);
const anomalies = await response.json();
```

```python Python theme={null}
import httpx

resp = httpx.get(
    "https://api.truthlocks.com/v1/risk/velocity",
    params={"min_score": 50, "limit": 25},
    headers={"X-API-Key": "tl_live_..."},
)
anomalies = resp.json()
```

Jedes Ergebnis enthält das Subjekt, den Aktionstyp, die aktuellen Fensterzählungen und den Geschwindigkeitsscore, der die Anomalie qualifiziert hat:

```json theme={null}
{
  "anomalies": [
    {
      "subject_id": "user_abc123",
      "action_type": "login.failed",
      "windows": {
        "1m": 5,
        "5m": 12,
        "1h": 30,
        "24h": 85
      },
      "velocity_score": 68,
      "last_recorded_at": "2027-07-03T14:22:00Z"
    }
  ],
  "cursor": "eyJsYXN0X2lkIjo..."
}
```

## Integrationsmuster

### Blockieren oder Drosseln bei hoher Geschwindigkeit

Verwenden Sie den Geschwindigkeitsscore aus der Datensatzantwort, um zu entscheiden, ob eine Aktion zugelassen, gedrosselt oder blockiert werden soll:

```javascript theme={null}
const result = await recordAction(subjectId, "api.request", ipAddress);

if (result.velocity_score >= 80) {
  await blockSubject(subjectId);
  await notifySecurityTeam(result);
} else if (result.velocity_score >= 60) {
  await throttleRequests(subjectId, { maxPerMinute: 5 });
} else if (result.velocity_score >= 30) {
  await addRateLimitWarning(subjectId);
}
```

### Mit ATO-Erkennung kombinieren

Die Geschwindigkeitsbewertung verfolgt jeden Aktionstyp über mehrere Zeitfenster hinweg, während [ATO-Erkennung](https://docs.truthlocks.com/de/guides/ato-detection.md) speziell für anmeldebasierte Kontoübernahmemuster mit integrierten Schwellenwertregeln und Alarmverwaltung optimiert ist. Verwenden Sie beides zusammen für einen mehrschichtigen Schutz:

* **Geschwindigkeitsbewertung** zur allgemeinen Missbrauchserkennung – API-Ratenmissbrauch, Transaktionsflut, Registrierungs-Spam
* **ATO-Erkennung** für fokussierte Anmeldesicherheit – Geschwindigkeit fehlgeschlagener Anmeldungen, Warnungen bei Credential Stuffing, Risikoprofile von Subjekten

### Über Webhooks überwachen

Konfigurieren Sie einen [Webhook-Endpunkt](https://docs.truthlocks.com/de/guides/webhooks.md), um Echtzeitbenachrichtigungen zu erhalten, wenn geschwindigkeitsbasierte Risikosignale erstellt werden, damit Ihr Sicherheitsteam ohne Abfragen reagieren kann.

### Benutzerdefinierte Aktionstypen

Sie können jeden Aktionstyp verfolgen, den Ihre Anwendung erzeugt. Häufige Beispiele:

| Aktionstyp | Anwendungsfall |
| :- | :- |
| `login.failed` | Fehlgeschlagene Anmeldeversuche |
| `api.request` | API-Aufruffrequenz |
| `transaction.create` | Zahlungs- oder Überweisungsversuche |
| `registration.attempt` | Spam bei der Kontoerstellung |
| `password.reset` | Missbrauch der Passwortzurücksetzung |
| `verification.request` | Überflutung von Verifizierungsanfragen |

## Nutzungsabrechnung

Jeder Aufruf von `POST /v1/risk/velocity/record` erhöht den Nutzungszähler `antifraud.velocity_records` für Ihren Abrechnungszyklus. Sie können Ihren Verbrauch mit der [Nutzungs-API](https://docs.truthlocks.com/de/api-reference/billing/usage.md) oder in der Konsole unter **Einstellungen > Abrechnung > Nutzung** im Abschnitt **Betrugsbekämpfung** überwachen.

> [!NOTE]
>
> Die Quoten für Geschwindigkeitsaufzeichnungen variieren je nach Planstufe. Details zu allen Anti-Fraud-Produkten mit Zähler finden Sie in der [Abrechnungsübersicht](https://docs.truthlocks.com/de/billing/overview.md#metered-products).

## Was als Nächstes kommt

* [API-Referenz zur Aufzeichnung von Geschwindigkeitsaktionen](https://docs.truthlocks.com/de/api-reference/risk/velocity-record.md)
* [API-Referenz zum Abrufen von Geschwindigkeitsfenstern](https://docs.truthlocks.com/de/api-reference/risk/velocity-windows.md)
* [API-Referenz zum Auflisten von Geschwindigkeitsanomalien](https://docs.truthlocks.com/de/api-reference/risk/velocity-anomalies.md)
* [Leitfaden für Risikosignale](https://docs.truthlocks.com/de/guides/risk-signals.md)
* [Leitfaden zur Erkennung von Kontoübernahmen](https://docs.truthlocks.com/de/guides/ato-detection.md)
* [Leitfaden zur Erkennung von Deepfakes und Identitätsdiebstahl](https://docs.truthlocks.com/de/guides/deepfake-detection.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.