Skip to content
VPNDetection

Plans and fields

What the VPNDetection free plan returns with or without a key, what a paid plan adds, and why a field your plan doesn't include is absent, not false.

Every answer from the API contains the fields your plan includes. This page explains what each plan returns, how a field your plan doesn't include appears in an answer, and what happens when a paid plan's quota runs out. Read it before you write rules, because the difference between a missing field and a false one decides what your rules let through.

The free plan

The free plan answers every lookup, with or without an API key, and has no daily or monthly cap. It returns:

  • is_vpn, so you can detect commercial VPN services.
  • is_tor and is_relay, with their detail objects, for Tor exits and privacy relays.
  • is_bot, for addresses that crawlers, monitors, scanners and other bots use.
  • is_anycast, is_bogon and the reverse DNS hostname.
  • location, to the country, with its continent, time zone and currency.
  • asn, the network that announces the address, with its type, prefix, country and RPKI status.

You may use the free plan in commercial products. You may not resell its answers or use them to build a competing service; the terms have the details.

Every paid plan returns every field. The plans differ only in how many lookups they include, so you choose a plan by volume, not by features. A paid plan adds:

  • Whether the address is a hosting server, a CDN, or a residential, datacenter, mobile or public proxy.
  • The evidence behind each classification: who operates it, how confident the classification is, and when the address was last seen.
  • For an address a bot uses, the bot object: whose bot it is, what it does and whether its operator vouches for the address. When you send the request's user agent, the answer also says whether the address bears it out.
  • Mobile carrier and satellite networks, and the services the address answers on.
  • The address's city and coordinates, the company that uses it and its abuse contact.

A new account can try every field before it chooses a plan. Pricing lists the plans, and What each plan answers lists every field by plan.

A missing field is not false

When your plan doesn't include a field, the field is absent from the answer. It is never false. An absent is_hosting means "not included in your plan", not "checked, and not a hosting server".

This matters when you write rules. A rule that treats a missing field as false lets through exactly the traffic it was written to catch. Check that a field is present before you act on its value, and decide what an unknown value means for each rule:

Node.js
const r = await client.lookup(ip);

// true, false, or null when your plan doesn't include the field
const hosting = r.isHosting ?? null;
if (hosting === null) {
    // Decide what an unknown answer means here, for example: use asn.type instead.
}

For a rule about hosting networks on the free plan, asn.type equal to hosting describes the network that announces the address, which works well for most traffic. See Block traffic from hosting networks.

Check what your key returns

To see which plan a key is on and how much of its quota it has used, call Plan and usage. The libraries expose it as a method:

Node.js
const entitlement = await client.myEntitlement();
console.log(entitlement.plan.name, entitlement.usage.requests);

When a paid plan's quota runs out

After a paid plan uses its quota, lookups keep working. They return the free plan's fields and include cap_reached: true until the quota resets, and they aren't charged. To keep receiving every field past the quota, turn on overage in the console's Billing page and set a cap; Rate Limits describes how overage is billed.

Because the answer keeps its shape, code that checks for a field's presence keeps working when the quota runs out: the paid fields are absent until it resets.

Next steps

To make sure the address you look up is the visitor's own, read Client IP addresses. To see these fields used in rules, read Screen VPN and proxy sign-ups.