> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Patterns
> Learn how the ready-made patterns surface abuse and fraud across linked identifiers, and how they are graded.
**\[BETA] Pattern analysis is in beta.** Patterns show technical relationships between identifiers over time. Identifier matching is reliable when the signals are available, but pattern severity and interpretation may vary by industry, action context, customer policy, and risk tolerance. During beta, new patterns may be added, existing ones may be removed, and thresholds for current patterns may change as the logic is calibrated. Review pattern results before taking any enforcement action.
Pattern analysis is still being calibrated because the same technical relationship can mean different business risk in different products. For example, one DeviceID linked to many UserHIDs may indicate bonus abuse, account farming, shared access, internal testing, or another scenario entirely, depending on your business model.
ShieldLabs identifies the technical relationships between IDs. Your team should review the affected entities, the action context, the history, and your own policy before deciding whether to monitor, challenge, restrict, review, or block.
Some abuse and fraud only shows up across many visits, so Patterns grade an entity by how its linked identifiers cluster over time, not on any single request. Eight relationship shapes point to it, such as many accounts on one device. They are starting points, not verdicts: several accounts on one device is often perfectly normal, and whether a given count is worth a look depends on your platform (an email provider may expect a dozen accounts behind one device, while a bank expects one account per customer), so read them with your own context.
A pattern flags an **entity**: a device, an account, a visitor, or a Local IP. When that entity's correlations cross a threshold, it surfaces on the dashboard for your team to review.
Patterns are a **dashboard feature**, not in the webhook payload.
## The eight patterns
Each pattern answers one question about how identifiers cluster over time. The name says the shape, the outcome says what it signals.
| Pattern | What it flags | Example abuse |
| -------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------ |
| **Many Accounts on One Device** | One device linked to many accounts. | Multi-accounting, account farms |
| **Many Devices on One Account** | One account used from many devices. | Account sharing, resale, takeover |
| **Changing IDs on One Account** | One account that keeps changing its device and visitor IDs. | Scripted activity, anti-detect browsers |
| **Many Accounts on One Local IP** | Many accounts behind the same Local IP. | Account farms, multi-accounting |
| **Multiple Countries on One Account** | One account active from many countries in a day. | Account sharing across regions, geo bypass |
| **Many Devices on One Visitor** | One visitor seen on many devices. | Fingerprint spoofing, anti-detect browsers |
| **Shared Local IP Across Multiple Accounts** | Accounts share a Local IP while using different devices and different public IPs. | Coordinated fraud, account farms |
| **New Device and New Country** | An existing account appears from a new device-and-country pair. | Account takeover, compromised credentials |
"Local IP" is the dashboard name for the visitor's local network address, used to correlate accounts that look distinct on their public IP.
Seven of the eight patterns count distinct accounts by **UserHID**, so they only form when you pass a hashed account id through [`checkAuthenticatedUser`](/setup/snippet) — this includes both Local IP patterns, which count the accounts sharing a network. Only **Many Devices on One Visitor** (it counts devices per visitor, not accounts) populates from `checkAnonymous` traffic alone. Pass the UserHID on signed-in calls to light the other seven up.
These eight are a ready-made starting set. ShieldLabs also returns the raw identifiers, IP, country, and [detection flags](/api/webhooks), so you can build your own correlations on top — or ask us to add a pattern for your platform.
## How grading works
Every pattern grades a flagged entity at one of two levels by counting its linked identifiers inside a rolling window.
* **Suspicious** - the entity crossed the lower threshold for that pattern in its window.
* **Dangerous** - the entity crossed the higher threshold. The strongest grade.
Only Suspicious and Dangerous are stored as detections. An entity that stays below the Suspicious threshold is the unflagged baseline: it is never recorded or surfaced.
### How each pattern triggers
A pattern grades an entity **Suspicious** when it crosses the lower count in its rolling window, and **Dangerous** at the higher count. These are the current default thresholds, with the window built into each one.
| Pattern | Suspicious | Dangerous |
| -------------------------------------------- | ----------------------------------------------- | ------------------------------------------------ |
| **Many Accounts on One Device** | 3–5 stable accounts in a month | 6+ accounts in a month |
| **Many Devices on One Account** | 5+ devices in 30 days | 15+ devices in 30 days |
| **Changing IDs on One Account** | 5+ ID changes in 7 days | 15+ ID changes in 7 days |
| **Many Accounts on One Local IP** | 3 in 24 hours, 4–5 in 7 days, or 6–9 in 30 days | 4+ in 24 hours, 6+ in 7 days, or 10+ in 30 days |
| **Multiple Countries on One Account** | 3+ countries in 24 hours | 5+ countries in 24 hours |
| **Many Devices on One Visitor** | 3+ devices per visitor | 8+ devices per visitor |
| **Shared Local IP Across Multiple Accounts** | 5+ accounts on different devices and public IPs | 15+ accounts on different devices and public IPs |
| **New Device and New Country** | 1 new device with a new country in 7 days | 3+ new device-and-country pairs in 7 days |
A tight window is what gives **Multiple Countries on One Account** its meaning: one account from several countries in a day is hard to explain as normal travel.
### How the level settles
* **The level never downgrades.** Once an entity reaches Dangerous, it stays Dangerous on later runs. Only its current count and last-seen time update.
* **Thresholds are server-side configuration.** The counts above are the current defaults, the same for every domain. There is no setting you control, and they can change as detection is tuned — read each row as the shape of what trips a pattern, not a number to hard-code against.
A legitimate user can land on a card too: a shared office network, a frequent traveler, a privacy browser. Confirm against your own context before you act.
## Where patterns live
Patterns are computed server-side from your historical identify data, then shown on the dashboard **Patterns** view. A background worker recomputes all eight for each verified domain about every 10 minutes, with one run at startup. There is nothing to trigger and no schedule to configure.
The Patterns view gives you three things.
* **Overlap summary** - deduplicated totals across all patterns, so you can tell whether a small set of entities is responsible for most flags. Per-card totals are not additive: an entity matching three patterns counts three times across the cards but once here.
* **Pattern cards** - one card per pattern, broken down per identifier, each with a Suspicious and a Dangerous sub-count. You can export flagged IDs to CSV or JSON, or open the [Data](/features/traffic-analytics) view filtered to that pattern.
* **Data view** - the request rows behind each flag, with the identifiers, country, signals, and Risk Score that produced it.
### Patterns are distinct from per-request signals
Patterns and the per-request Risk Score answer different questions. Use the right one for the job.
| | Risk Score | Patterns |
| ----------------- | ----------------------------- | ------------------------------------------------------- |
| **Scope** | One visit, in real time | An entity, across history |
| **Delivery** | Webhook and History API | Dashboard Patterns view only |
| **Grades** | 0–100 | Suspicious / Dangerous |
| **You act on it** | In your own code, per request | By exporting flagged IDs and acting in your own systems |
## You export the IDs and decide
The Patterns view is read-only. ShieldLabs surfaces the flagged entities. Your own code owns every allow, challenge, review, or block decision. There is no in-product rules engine and no threshold UI.
The workflow is short.
In the overlap summary, compare total against unique affected IDs. A large gap means a few entities are tripping many patterns each — and an entity matching the most patterns is usually the most clearly coordinated.
Read the per-identifier blocks on the card and their Suspicious and Dangerous sub-counts.
Open the Data view to inspect the request rows behind the flag and confirm context.
Export the flagged IDs as CSV or JSON, then apply your own policy.
The exported IDs join cleanly to the per-request records you receive over [webhooks](/setup/webhooks) and read through the [History API](/api/server-api), so they load straight into your fraud, billing, or moderation tooling.
Exports are free. They do not consume request balance. [Billing](/billing) is per identification only.
## Next steps
The per-request 0-100 score, its bands, and the signals behind it.
Use the Risk Score and patterns to flag multi-accounting at signup.
The dashboard, the Data view, and how traffic quality is measured.