Single lookups
GET/api/v1/ip/{ip}Who operates an addressAsk: One IPv4 address. The most common call: an address from a log, an alert or a report, and the question which VPN or proxy service runs it.
Answer: anonymous and types (VPN, TOR, RELAY …), serviceCategory (the service we measured: VPN, residential or datacenter proxy), infrastructure (the kind of network, from datacenter lists and PeeringDB, with infrastructureBasis), sharing (how far the address identifies an actor, with its rule), attribution — each provider with its weight (share of the days it was seen, recent days counting more), its confidence (0–3) and the methods behind it — and evidence with first and last sighting, observation count and confidenceBasis, the computation behind the confidence in one sentence. network, asn and location say where it sits; latest names the most recent provider where it is not the leader; feeds lists external lists naming it. An address we never saw but whose announced prefix we know is answered by interpolation (method: interpolated); at very low confidence (0) that answer describes the network and is not anonymous. A miss is a 404 with a reason, never an all-clear.
| min_confidence | 0–3, optional. An answer below it is a 404 below_min_confidence; without it every answer comes back. |
Example request
curl -s "https://vpndb.io/api/v1/ip/37.120.237.182" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/ip/{ip}/historyEvery week of an addressAsk: The record of one address week by week since probing began — for an incident months ago, the week governs, not today's verdict.
Answer: weeks: each week's status (probe, scan, interpolated, none), its providers with weights, the days seen and the probes; providers summarises who held the address and when. Network, ASN and country come from the local tables even for an address with no evidence at all.
Example request
curl -s "https://vpndb.io/api/v1/ip/37.120.237.182/history" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/prefix/{cidr}Any range, and who is inside itAsk: Any IPv4 CIDR — an announced prefix or any other range. Every known exit address inside it counts, from our probing, the enriched snapshot and scan certificates together, each once.
Answer: observedIps, attribution by the provider of each address's most recent sighting, sources (how many addresses each source knows), prefixes.contained and prefixes.covering — the announced prefixes the range meets — networks (origin ASNs), countries by GeoIP share of the address space, and feeds.
Example request
curl -s "https://vpndb.io/api/v1/prefix/37.19.196.0%2F23" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/prefix/{cidr}/addressesEvery address of a prefix, in a windowAsk: The address table of a prefix for a time window: which addresses were used, by whom, through which tunnel — and the rest of each announced prefix by interpolation.
Answer: addresses a page at a time, each with its providers and their days, methods, pool, first and last seen; facets counts providers, methods and pools for the filters; observed, interpolated and total say how many there are; nextCursor continues.
| from, to | The window, yyyy-MM-dd; default the last 30 days. |
| provider, method, pool | Filters; method takes several, comma-separated. |
| size, cursor | Page size (1–500) and continuation. |
Example request
curl -s "https://vpndb.io/api/v1/prefix/37.19.196.0%2F23/addresses?size=3" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/prefix/{cidr}/timelineHow a prefix was probed, day by dayAsk: The daily probe activity of a range, to choose a window for the address table.
Answer: days with probe events and distinct addresses per day; firstSeen/lastSeen span every source.
Example request
curl -s "https://vpndb.io/api/v1/prefix/37.19.196.0%2F23/timeline" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
Networks, organisations and countries
GET/api/v1/asn/{asn}A network and its providersAsk: One ASN: how much anonymising infrastructure it carries and whose.
Answer: observedIps, networkCount (prefixes), attribution — the provider distribution, each with addresses and share — singleTenant, infrastructureMix, collateral (what an ASN-wide block would hit), sources and aggregatedAt, when the union behind the figures was computed.
Example request
curl -s "https://vpndb.io/api/v1/asn/9009" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/asn/{asn}/networksEvery prefix of a networkAsk: All announced prefixes of an ASN that hold a known exit address — not only the busiest — to block or hunt precisely.
Answer: networks, each prefix with its size, known addresses and providers; total, matching, shared; nextCursor.
| provider | Only prefixes this provider was seen in. |
| q | Part of a prefix, or AS123. |
| shared | true: only prefixes with several providers. |
| sort, size, cursor | tenancy, addresses or address; page size 1–500. |
Example request
curl -s "https://vpndb.io/api/v1/asn/9009/networks?size=3" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/org/{id}A company and all its networksAsk: An AS organisation by its CAIDA id (from /suggest) — the way in when a report names a hosting company rather than an ASN.
Answer: Every registered network (asns) with what we observed in each, and the organisation as one network: attribution across all its ASNs, providerCount, networkCount, observedAsns, collateral. sharesName warns when several organisations carry the same name.
Example request
curl -s "https://vpndb.io/api/v1/org/ORG-DL201-RIPE" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/org/{id}/networksEvery prefix of a companyAsk: The prefixes of all of an organisation's networks together, with the ASN announcing each.
Answer: The same list as for one network, across all its ASNs, with the same filters.
Example request
curl -s "https://vpndb.io/api/v1/org/ORG-DL201-RIPE/networks?provider=nordvpn&size=3" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/country/{cc}The infrastructure located in a countryAsk: A country by its two-letter code: which networks hold its exit addresses and which providers run there. A country is where DB-IP locates each address, not where its network is registered.
Answer: vpn and residential apart, each with observedIps, prefixes, providers (addresses, prefixes, share) and asns (addresses, prefixes, their three largest providers), largest first; unannouncedIps counts exits in no announced prefix.
Example request
curl -s "https://vpndb.io/api/v1/country/DE" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/countriesEvery country at a glanceAsk: All countries with known exit addresses — the data behind the world map.
Answer: countries, each with VPN exits, prefixes, providers, networks and residential exits, most VPN exits first.
Example request
curl -s "https://vpndb.io/api/v1/countries" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
Providers
GET/api/v1/service/{tag}A provider's profileAsk: One provider by its tag (nordvpn, mullvad …): how large it is, where it runs and how current our view is.
Answer: status (ACTIVE, DEGRADED, DISCONTINUED), observedIps, networkCount and countries, geographicPresence by country, asns it exits from, the protocols seen, activity over time, coLocatedWith — providers sharing its networks — first and last sighting, and aggregatedAt.
Example request
curl -s "https://vpndb.io/api/v1/service/nordvpn" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/service/{tag}/networksEvery network a provider exits fromAsk: The reverse lookup for retro-hunting: all prefixes of one provider, to search a year of logs for them.
Answer: networks, each prefix with the provider's addresses there, a confidence (from the count of addresses), the block's size and coverage — how much of the block is the provider's —, its network class and how many providers share it; nextCursor walks the whole set. For a blocklist, filter by coverage: a cloud block with one of the provider's servers in it is listed, at very low coverage.
| min_confidence | 0–3; default 1. Counts the provider's addresses, not their share of the block. |
| min_coverage | 0–3: only blocks of which at least this much is the provider's — 3 over 50 %, 2 from 10 %, 1 from 1 %. For a blocklist, 2. |
| min_observed | Only blocks with at least this many of the provider's addresses. |
| max_size | The largest block kept, as a prefix length: 20 keeps a /20 and smaller. |
| exclude_datacenter | true leaves out blocks a datacenter or cloud list covers. |
| size, cursor | Page size (1–1000) and continuation. |
Example request
curl -s "https://vpndb.io/api/v1/service/nordvpn/networks?size=3" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/servicesEvery provider at a glanceAsk: The provider overview: all providers with their size.
Answer: providers, each with category (VPN or residential), exit addresses (all and last 30 days), prefixes, networks, countries, first and last sighting.
Example request
curl -s "https://vpndb.io/api/v1/services" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
The Tor network
GET/api/v1/torThe Tor network at a glanceAsk: Where Tor traffic leaves the internet and who runs it: the Tor Project's relay list placed with our routing and country tables.
Answer: counts (exit addresses and relays, guards, bridges, networks, prefixes, countries), concentration, exitNetworks, exitCountries and exitPrefixes with their share of the exit traffic, relayNetworks, and reachedVia — the Tor exits our probing reached through a VPN's Tor feature.
Example request
curl -s "https://vpndb.io/api/v1/tor" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/tor/relaysEvery running Tor relay, for detectionAsk: Every relay's address and port, to find Tor clients inside a network: a connection to a guard is the first hop of every Tor client.
Answer: relays, each with address, OR port, role (exit, guard, middle), exit addresses, network, country, fingerprint, nickname and first seen; total and nextCursor. As CSV with format=csv.
| role | exit, guard or middle; default all. |
| format | json (default) or csv. |
| size, cursor | Page size (1–10000, default 200) and continuation. |
Example request
curl -s "https://vpndb.io/api/v1/tor/relays?role=exit&size=3" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
Many addresses, search and the dataset
POST/api/v1/bulkMany addresses at onceAsk: Up to 10,000 addresses in one request — a log extract, an IOC list.
Answer: results, one row per address with provider, its weight, span and the number of providers (providerWeight, providerFirstSeen, providerLastSeen, providerCount, runnerUp), sharing as in the single lookup, firstSeen and lastSeen of the address — confidence — about the address being an exit, not about the provider —, the computation behind it, method and last seen — the single lookup's answer, shortened; total, anonymous and unknown count the rows; byProvider and byAsn tally them.
| min_confidence | 0–3, optional, in the body (or the query). Rows below it keep address, network, country and lists, lose the verdict and say why in note; belowMinConfidence counts them. |
Example request
curl -s -X POST "https://vpndb.io/api/v1/bulk" \
-H "Authorization: Bearer $VPNDB_KEY" \
-H "Content-Type: application/json" \
-d '{"ips":["37.120.237.182","107.189.12.7","10.0.0.1"]}'Sign in to see this request's real answer.
GET/api/v1/searchResolve free textAsk: Any query — an address, a prefix, AS9009, a provider, a country — resolved to the entity it names.
Answer: resolvedAs and matches, each with a type, a label and the page it opens.
Example request
curl -s "https://vpndb.io/api/v1/search?q=AS9009" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/suggestSuggestions as you typeAsk: A partial name: providers, organisations, countries, networks, addresses.
Answer: suggestions, each with a type, a label, a note (country, networks, exits) and whether we hold observations behind it; more says how many are not shown.
| q | What was typed. |
| limit | 1–50, default 10. |
Example request
curl -s "https://vpndb.io/api/v1/suggest?q=nord&limit=3" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.
GET/api/v1/metaThe datasetno key neededAsk: Version, size and freshness of the data — to cite with a result. No key needed.
Answer: datasetVersion, counts (exit addresses, providers, networks), coverage and freshness — what the data reaches and how current it is — and the external feeds loaded.
Example request
curl -s "https://vpndb.io/api/v1/meta"
Sign in to see this request's real answer.
GET/api/v1/openapi.yamlThis specificationno key neededAsk: The OpenAPI 3.1 document of the whole API, for Swagger UI, Postman or a client generator. No key needed.
Answer: YAML: every endpoint, parameter, response, error and both ways to authenticate.
Example request
curl -s "https://vpndb.io/api/v1/openapi.yaml"
Sign in to see this request's real answer.
GET/api/v1/sourcesWhere the data comes fromadministrators onlyAsk: Provenance of every external source, the pipeline's health and what was declined. Administrators only.
Answer: feeds with licence, clearance, age and records; health with each check's verdict; declined with the reason; notices that must ship with the data.
Example request
curl -s "https://vpndb.io/api/v1/sources" \
-H "Authorization: Bearer $VPNDB_KEY"
Sign in to see this request's real answer.