Check addresses in bulk
Check a file, a table or a log of IP addresses for VPNs, Tor and proxies with the VPNDetection CLI, the batch API, BigQuery or a database.
When you have many addresses to check, such as a day of logs or a table of past sign-ups, one request per address is slow and uses quota. This guide compares four faster ways to check a list, shows each one, and helps you choose.
| Method | Best for | Plan |
|---|---|---|
| CLI | A file of addresses, checked from a terminal | Any |
| Batch API | Up to 1,000 addresses per request from your code | Paid |
| BigQuery | Addresses already stored in a BigQuery table | Free for the Open databases |
| Database | Millions of addresses, checked locally | Free for the Open databases; the others need a license |
Use the CLI
The CLI reads addresses and ranges from files and standard input, and streams the results, so even a large file starts producing output immediately. bulk always prints a machine format, CSV or JSON Lines, which suits a script:
vpndetection bulk addresses.txt --csv > results.csv
vpndetection bulk addresses.txt --jsonl | jq -r 'select(.is_vpn) | .ip'To keep only the fields you need, list them with -f:
vpndetection bulk addresses.txt --jsonl -f ip,is_vpn,vpn.providerRun vpndetection login first to check with your key, so the answers carry every field your plan includes.
Use the batch API
On a paid plan, POST /batch answers up to 1,000 addresses in one request:
curl -X POST https://api.vpndetection.io/batch \
-H "Authorization: Bearer $VPNDETECTION_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ips": ["45.83.91.1", "1.1.1.1"]}'The answer holds two maps keyed by the addresses you sent: results, with each answer exactly as a single lookup would return it, and errors, with each address that couldn't be answered and why. One address failing never affects the others, and duplicates count once. The official libraries split a longer list into batches for you; see Batch.
Use BigQuery
If your addresses are already in BigQuery, join them with our datasets in SQL, with nothing to download. The Open datasets, such as Tor IP and Relay IP, are free. After you subscribe to the listing, each table has a function of the same name that looks an address up:
SELECT l.*, vpndetection_open.relay_ip_v1(l.ip).provider AS relay
FROM mydataset.logins AS lBigQuery covers subscribing, every table and its functions.
Use a database
For millions of addresses, download the database you need and look each address up locally, at no cost per lookup. An MMDB file answers in microseconds, and a CSV file loads into your own database or warehouse. See Use the databases.
Choose a method
- A one-off check of a file: the CLI.
- A recurring job in your code: the batch API, through an official library.
- Data that already lives in BigQuery: BigQuery, with no data leaving your project.
- Continuous, high-volume enrichment: a database, refreshed daily.
Next steps
To act on single addresses as they arrive instead, see Screen VPN and proxy sign-ups or Protect a web app.