clusterUUID
clusterUUID is a probabilistic, pseudonymous identifier that groups events likely coming from the same browser or browser configuration. It lets you associate requests across page loads, tabs, and visits without user action.
How clusterUUID is computed depends on the Request Type bound to your API key: Basic, Standard, or Advanced.
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: low — may change 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.
Standard — Full-context
Combines the browser fingerprint plus Synthient IP intelligence (ASN/ISP, residential vs. hosting/VPN/relay classification, geosignals) plus first-party cookie binding.
- Higher stability & uniqueness than Basic by adding network context and cookie persistence
- First-party cookie helps persist identity across sessions and routine browser/OS updates
- Privacy network awareness: detects/labels VPNs, hosting, and iCloud Private Relay to reduce crowding on shared egress IPs
- IP intel source: Synthient. In practice, Synthient’s ISP labeling and geolocation are more prone to mislabels than MaxMind (used by Advanced), which can yield more resolution mistakes (occasional over-/under-grouping)
- No static-IP pinning (available in Advanced)
Best for: most production sites that want durable identity with low collision rates and strong fraud/abuse controls.
Advanced — Full-context (+ MaxMind)
Combines the browser fingerprint plus MaxMind IP intelligence (ASN/ISP, residential vs. hosting/VPN/relay classification, geosignals) plus first-party cookie binding.
- Highest stability & uniqueness; better differentiation on noisy networks, NATs, VPNs, and privacy relays
- Static-IP pinning: when an address is confidently non-anonymous and stable, the cluster can be anchored to further reduce collisions (with graceful fallback if conditions change)
- IP intel source: MaxMind. Its geolocation and ISP/hosting labeling are typically more accurate than Synthient’s, yielding fewer resolution mistakes and tighter clustering
Best for: high-stakes production environments needing maximum persistence and minimal collisions.
Quick comparison
| Dimension | Basic | Standard | Advanced |
|---|---|---|---|
| Inputs | Browser fingerprint | Fingerprint + Synthient IP intel + first-party cookie | Fingerprint + MaxMind IP intel + first-party cookie |
| IP intel source | — | Synthient | MaxMind |
| Uniqueness | Moderate (look-alike devices can collide) | High | Highest (adds static-IP pinning when safe) |
| Persistence across updates | Lower | High | Highest |
| Network awareness | None | Classifies IPs (residential, hosting, VPN/relay), geosignals | Everything in Standard + static-IP pinning |
| IP intel accuracy | — | Good, but more mistakes vs Advanced | Higher accuracy → fewer resolution mistakes |
| Ideal use | Bot screening, minimal data | Fraud prevention, account integrity, analytics dedupe | High-risk fraud prevention, precise user resolution |
Rotation scenarios (when clusterUUID might change)
Basic
- Browser/OS version changes
- GPU/driver switches and other environmental changes
- Spoofing caused by anti-detect techniques
Standard
- Cookie cleared/blocked, or third-party tools that impair storage
- Significant device/browser resets or major fingerprint changes
- Network context shifts (e.g., new ISP, VPN/relay behavior changes)
- Synthient mislabels (ISP/geo) leading to temporary over-/under-grouping
- Anti-detect spoofing or unforeseen browser vendor changes
Advanced
- Cookie cleared/blocked, or storage impaired
- Major environmental changes (hardware swaps, significant fingerprint drift)
- Rare MaxMind mislabels or classification updates
- Static-IP pin conditions no longer met (e.g., IP becomes anonymous/unstable)
- Anti-detect spoofing or unforeseen browser vendor changes
How to use clusterUUID
- Durable key (Standard/Advanced): de-duplicate analytics events, join sessions, throttle/limit abuse per user/device cluster.
- Grouping hint (Basic): treat collisions as possible—combine with OPJS signals (e.g.,
botScore, anti-detect heuristics). - Never treat as a permanent identity. It’s a probabilistic identifier and may rotate as users change devices, browsers, or network conditions.
FAQ
Is clusterUUID PII?
By itself it’s a pseudonymous identifier. Whether it’s personal data depends on your use and jurisdiction. Consult counsel and your privacy policy.
Can two people share a clusterUUID?
Yes—especially in Basic mode or on shared/identical setups (kiosks, labs, same model/OS). Standard reduces this via cookie binding and network context; Advanced reduces it further via MaxMind’s higher-accuracy labeling and static-IP pinning.
Why did a user’s clusterUUID change overnight?
Common causes include cookie clearing/blocks, substantial fingerprint drift after updates, relay/VPN behavior changes, and IP-intel mislabels. This is more likely in Standard (Synthient) than Advanced (MaxMind). If you believe two IDs are the same browser, contact support with both values so we can investigate.
Does clearing cookies affect Standard/Advanced?
Yes. Cookie loss removes one persistence layer; clustering can still succeed from fingerprint + network, but long-term stability may drop.
For how request types affect computation and credits, see Getting Started → Request Types.