Velocity and anomaly scoring

The velocity and anomaly scoring API tracks how frequently a subject performs a given action across multiple rolling time windows — 1 minute, 5 minutes, 1 hour, and 24 hours. When the weighted velocity score crosses a threshold, the platform automatically creates a risk signal, connecting anomaly detection directly to the Anti-Fraud Identity Firewall pipeline.

Velocity scoring is part of the Anti-Fraud Identity Firewall. Signals generated by velocity anomalies flow into the same pipeline as other fraud signals, so you can query and review them from the Risk & Fraud > Signals console page or the list signals endpoint.

How it works

Record actions

Call POST /v1/risk/velocity/record each time a subject performs a tracked action — login attempts, API calls, transaction requests, or any custom action type.

Rolling window tracking

The platform increments counters for the subject and action type across four rolling windows (1 m, 5 m, 1 h, 24 h). Windows reset automatically when they expire.

Weighted scoring

A velocity score is computed from the window counts. Short windows are weighted more heavily to detect bursts: 1 m × 30, 5 m × 20, 1 h × 10, 24 h × 5.

Automatic signal ingestion

When the velocity score reaches 60 or above, the platform automatically ingests a risk signal with signal_type: "velocity". You don’t need a separate API call.

Review and respond

Query velocity windows for a subject, list high-velocity anomalies across your tenant, and review signals in the console or via the API.

Prerequisites

An active Truthlocks tenant with an API key
Action event data from your application (login attempts, API calls, transactions, or any repeatable action)

Recording an action

Send a POST request to /v1/risk/velocity/record with the subject, action type, and optional metadata:

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"
  }'

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();

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()

The response returns the current window counts, the computed velocity score, and whether a risk signal was auto-ingested:

{
  "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-..."
}

Scoring model

The velocity score is a weighted sum of action counts across four rolling windows. Short windows carry higher weight to prioritize burst detection:

Window	Weight	Purpose
1 minute	30	Detects rapid bursts (credential stuffing, automated attacks)
5 minutes	20	Catches sustained short-term abuse
1 hour	10	Identifies medium-term patterns
24 hours	5	Flags persistent anomalies over longer periods

The final score is capped at 100. When the score reaches 60 or above, a risk signal is automatically ingested with signal_type: "velocity".

Score interpretation

Score range	Interpretation	Example
0–29	Normal	Typical user activity
30–59	Elevated	Above-average frequency, worth monitoring
60–79	High	Likely automated or abusive — signal auto-ingested
80–100	Critical	Strong anomaly — immediate investigation recommended

Querying velocity windows

Retrieve the current velocity windows for a specific subject:

curl https://api.truthlocks.com/v1/risk/velocity/user_abc123 \
  -H "X-API-Key: tl_live_..."

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

import httpx

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

The response includes all tracked action types for the subject, with counts per window and the computed velocity score for each:

{
  "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
    }
  ]
}

Listing high-velocity anomalies

Query subjects with velocity scores above a threshold across your tenant:

curl "https://api.truthlocks.com/v1/risk/velocity?min_score=50&limit=25" \
  -H "X-API-Key: tl_live_..."

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();

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()

Each result includes the subject, action type, current window counts, and the velocity score that qualified the anomaly:

{
  "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..."
}

Integration patterns

Block or throttle on high velocity

Use the velocity score from the record response to decide whether to allow, throttle, or block an action:

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);
}

Combine with ATO detection

Velocity scoring tracks any action type across multiple time windows, while ATO detection is specifically optimized for login-based account takeover patterns with built-in threshold rules and alert management. Use both together for layered protection:

Velocity scoring for general abuse detection — API rate abuse, transaction flooding, registration spam
ATO detection for focused login security — failed login velocity, credential stuffing alerts, subject risk profiles

Monitor via webhooks

Configure a webhook endpoint to receive real-time notifications when velocity-based risk signals are created, so your security team can respond without polling.

Custom action types

You can track any action type your application produces. Common examples:

Action type	Use case
`login.failed`	Failed login attempts
`api.request`	API call frequency
`transaction.create`	Payment or transfer attempts
`registration.attempt`	Account creation spam
`password.reset`	Password reset abuse
`verification.request`	Verification request flooding

Usage metering

Each call to POST /v1/risk/velocity/record increments the antifraud.velocity_records usage counter for your billing cycle. You can monitor your consumption with the usage API or in the console at Settings > Billing > Usage under the Anti-Fraud section.

Velocity record quotas vary by plan tier. See the billing overview for details on all Anti-Fraud metered products.

Getting Started

Guides

Trust & Compliance

Security

Operations

Enterprise Packs

Machine Identity (MAIP)

Risk & Fraud

Specification

SDKs

How it works

Prerequisites

Recording an action

Scoring model

Score interpretation

Querying velocity windows

Listing high-velocity anomalies

Integration patterns

Block or throttle on high velocity

Combine with ATO detection

Monitor via webhooks

Custom action types

Usage metering

What’s next

​How it works

​Prerequisites

​Recording an action

​Scoring model

​Score interpretation

​Querying velocity windows

​Listing high-velocity anomalies

​Integration patterns

​Block or throttle on high velocity

​Combine with ATO detection

​Monitor via webhooks

​Custom action types

​Usage metering

​What’s next

How it works

Prerequisites

Recording an action

Scoring model

Score interpretation

Querying velocity windows

Listing high-velocity anomalies

Integration patterns

Block or throttle on high velocity

Combine with ATO detection

Monitor via webhooks

Custom action types

Usage metering

What’s next