clusterUUID
clusterUUID is a probabilistic, pseudonymous identifier that groups events which likely come from the same user/device. It lets you associate requests across page loads, tabs, and visits without user action.
How clusterUUID is computed depends on the Request Type (picked when you create an API key). See Basic vs Advanced below.
How it’s computed
Basic — Fingerprint-only
Built solely from on-device/browser signals (e.g., UA/Client Hints, WebGL/GPU, canvas, storage quota, fonts, media queries).
- No third-party IP intelligence
- No network context and no first-party cookie binding
- Uniqueness: moderate — look-alike devices can collide
- Durability: lower — changes when the browser/OS updates or the environment shifts
Best for: lightweight bot screening and privacy-sensitive flows where you don’t want network data involved.
Advanced — Full-context
Combines the browser fingerprint plus MaxMind IP intelligence (ASN/ISP, residential vs hosting/VPN/relay, geosignals) plus first-party cookie binding.
- High stability & uniqueness: designed to persist across browser/OS updates, IP changes, and environment shifts
- Privacy network awareness: detects/labels iCloud Private Relay, VPNs, hosting, etc., to reduce crowding on shared egress IPs
- Static-IP pinning: when an IP is confidently non-anonymous and stable, it can further anchor the cluster to reduce collisions
- First-party cookie binding: OPJS writes/reads a first-party cookie to further assist in persisting identity across sessions
Best for: fraud/abuse prevention, account defense, and analytics deduplication where accurate user resolution matters.
Quick comparison
| Dimension | Basic | Advanced |
|---|---|---|
| Inputs | Browser fingerprint | Fingerprint + MaxMind IP intel + first-party cookie |
| Uniqueness | Moderate; collisions for look-alike devices | High; fewer collisions (handles NATs, VPNs/relays better) |
| Persistence across updates | Lower | High (cookie binding + network intelligence) |
| Network awareness | None | Classifies IPs (residential, hosting, VPN/relay), geosignals, static-IP pinning |
| Ideal use | Bot screening, minimal data collection | Fraud prevention, account integrity, analytics dedupe |
Rotation scenarios (when clusterUUID might change)
Basic
- Browser/OS version changes
- GPU/driver switches, and other environmental changes
- Spoofing caused by anti-detect techniques
Advanced
- Major environmental changes such as hardware swaps
- Environmental spoofing caused by anti-detect techniques
- Unforseeable future changes by browser vendors
How to use clusterUUID
- As a durable key (Advanced): de-duplicate analytics events, join sessions, throttle abuse per user/device cluster.
- As a grouping hint (Basic): treat collisions as possible—combine with other OPJS signals.
- Never treat as a permanent identity. It’s a probabilistic identifier that can rotate as users change browsers or devices.
FAQ
Is clusterUUID PII?
By itself it’s a pseudonymous identifier. Whether it’s personal data can depend on how you use it and your jurisdiction. Consult your counsel and privacy policy.
Can two people share a clusterUUID?
Yes—especially in Basic mode or on shared/identical setups (kiosks, labs, same model/OS). Advanced reduces this via network intelligence and cookie binding.
Why did a user’s clusterUUID change overnight?
Most often: you’re using Basic mode. However, user tracking is often heuristic and can sometimes lead to errors. These errors can be caused by inaccurate or evolving IP intelligence, unforseeable browser vendor changes, and errors on our part. If you believe you've spotted improper behavior, please contact support with the values of the IDs that you know for sure are the same browser so we can diagnose the issue.
For how request types affect computation and credits, see Getting Started → Request Types.