# VPNDetection

> Classifies an IP address as VPN, proxy, hosting, Tor, CDN or privacy relay, and returns
> the evidence: which operator, how strongly supported, when last observed. One GET per
> address. Eight independent datasets, rebuilt daily.

Site: https://vpndetection.io
Docs: https://docs.vpndetection.io
API:  https://api.vpndetection.io/{ip}

## The call

```
curl "https://api.vpndetection.io/45.83.91.1" \
  -H "Authorization: Bearer $VPNDETECTION_API_KEY"
```

IPv4 and IPv6 on the same endpoint. Without a key you still get an answer, narrower.

## The response

```json
{
  "ip": "45.83.91.1",
  "is_vpn": true,
  "is_hosting": true,
  "is_tor": false,
  "is_relay": false,
  "is_cdn": false,
  "is_resproxy": false,
  "is_dcproxy": false,
  "is_mobproxy": false,
  "vpn": {
    "provider": "mullvad",
    "confidence": "high",
    "method": "scan",
    "last_seen": "2026-09-02"
  },
  "hosting": { "provider": "m247", "confidence": "high", "last_seen": "2026-09-02" },
  "tor": {},
  "relay": {},
  "cdn": {},
  "resproxy": {},
  "dcproxy": {},
  "mobproxy": {}
}
```

## Flags

- is_vpn: A commercial VPN exit. The operator is named in the vpn object.
- is_hosting: Leased hosting or cloud space. Infrastructure, not anonymity on its own.
- is_tor: A Tor exit node, from the public exit set, rebuilt daily.
- is_relay: A platform privacy relay, such as iCloud Private Relay.
- is_cdn: A content-delivery edge. Grouped with hosting, not with anonymity.
- is_resproxy: Seen in a residential proxy pool over a rolling 90-day window.
- is_dcproxy: Seen in a datacenter proxy pool over the same window.
- is_mobproxy: Seen in a mobile proxy pool riding carrier-assigned space.

## Reading it correctly

- Absent is unknown, never false. A field your plan does not include is omitted from the response. Do not read a missing key as a negative answer; read it as a question you did not buy an answer to.
- An empty object is a checked answer. A flag that is present always answers. Its detail object comes back as {} when the dataset was queried and nothing matched - that is "we looked", not "we do not know".
- Bogons never reach us and never bill. Private, loopback, link-local, documentation and multicast ranges, including their 6to4 and Teredo forms, are answered by the client without a request. Every official SDK does this; if you call the endpoint directly, do it yourself.
- Retry-After separates the two 429s. Present means a transient rate limit and retrying works. Absent means a monthly allowance is spent and retrying will not help. Branch on the header, not on the status.
- A 5xx is ours. Retry with exponential backoff and jitter. The official clients already do.
- Provider ids are stable. A provider id does not change between builds, so a rule keyed on one keeps working as that operator's ranges rotate. Join on the id, not on a display name.
- Classifications are probabilistic. They are inferences from measurement, published operator data and public registration records. They can be wrong or go stale. Do not make them the sole basis for denying a person access to a service.

## What each plan returns

- No key: ip and is_vpn, under a small daily allowance.
- Free: The same fields, at 50,000 requests a month.
- Starter: All eight flags, plus provider and last_seen on the VPN match.
- Scale: Adds the detail object behind hosting, Tor, relay and CDN, and the three proxy flags.
- Max: Every field, including confidence, method and the proxy persistence counts.

## Status codes

- 200 resolved; the flags and their detail are in the body
- 400 not a valid IPv4 or IPv6 address
- 401 key missing, revoked or not yet active
- 429 rate limited (Retry-After present) or allowance spent (absent)
- 5xx ours; retry with exponential backoff and jitter

## Bulk

Do not loop the API over a list you already hold.

- Whole datasets download as CSVGZ, and MMDB where published: https://vpndetection.io/databases/vpn-ip
- Per-block aggregates need no key and are crawlable to /16: https://vpndetection.io/ips
- Per-address pages exist but are noindex and cost a live look-up: crawl the blocks instead

## Pages

- https://vpndetection.io/ai-agents: this contract, in full, as a page
- https://vpndetection.io/api: the API, with a live lookup you can try without a key
- https://vpndetection.io/pricing: plans, quotas and what each tier returns
- https://vpndetection.io/ips: the IPv4 address space by block
- https://vpndetection.io/bogon: the reserved ranges we answer client-side and never bill
- https://vpndetection.io/terms, /privacy, /aup, /dpa: the legal documents

## Caveat

Classifications are inferences from measurement, published operator data and public
registration records. They can be wrong or go stale. Do not make one the sole basis for
denying a person access to a service.