What is the difference between a proxy, a VPN, and Tor?

Proxy: Forwards traffic through another server and mainly masks the IP. VPN: Routes traffic through a remote server and encrypts and tunnels the connection. Tor: Routes traffic through multiple nodes to provide stronger anonymity.

IP Security API

Overview

The IP Security API returns detailed threat flags for any IPv4 or IPv6 address. It detects whether an IP is associated with a VPN, a proxy, a residential proxy, a Tor exit node, a relay, bot activity, spam activity, or known attacker behavior. For VPN and proxy signals, it also returns confidence scores, provider names, and last seen timestamps when available. This helps you reliably identify anonymous and masked traffic before it reaches your systems.

The API also checks whether the IP is linked to a cloud provider and, when available, returns the cloud provider name.

IP Security API Lookup Endpoints

The IP Security API offers two endpoints for IP risk assessment: single lookup and bulk lookup. Below you’ll find details and examples for both endpoints, along with the full list of optional query parameters and how to use them with each endpoint.

Note

Please note the following:

After adding your website as a Request Origin in the Billing Dashboard, you can call the endpoints below directly from the client-side without including the apiKey query parameter to help prevent unauthorized use of your API key.
Base URL (v3): https://api.ipgeolocation.io/v3/security
Responses are returned in JSON by default. To receive XML, add output=xml . You can also explicitly request JSON with output=json .

Important

Each successful Security lookup costs 2 credits per valid IP. The X-Credits-Charged response header shows the total credits charged for the request. For details, please refer to our Credits Usage Guide.

Single IP Lookup Endpoint

1.Lookup the caller IP (no `ip` parameter)

If you don’t pass the ip parameter, the API automatically detects the public IP address of the requesting client and returns its threat score and security signals (for example, VPN/proxy/Tor/bot/spam/hosting indicators and the provider names when available). Use this option when you want to assess the IP risk of the requesting client without specifying an IP address.

curl -X GET 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY'

Response

1{
2  "ip": "5.187.10.7",
3  "security": {
4    "threat_score": 75,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_provider_names": [
8      "Evomi Proxy",
9      "IPRoyal",
10      "922 Proxy"
11    ],
12    "proxy_confidence_score": 99,
13    "proxy_last_seen": "2026-01-28",
14    "is_residential_proxy": true,
15    "is_vpn": false,
16    "vpn_provider_names": [],
17    "vpn_confidence_score": 0,
18    "vpn_last_seen": "",
19    "is_relay": false,
20    "relay_provider_name": "",
21    "is_anonymous": true,
22    "is_known_attacker": true,
23    "is_bot": false,
24    "is_spam": false,
25    "is_cloud_provider": false,
26    "cloud_provider_name": ""
27  }
28}

2.Lookup a specific IP address

Pass the ip parameter to check a specific IPv4 or IPv6 address. The API returns the threat score and security signals (such as VPN, proxy, residential proxy, Tor, bot, spam, relay, and hosting flags), along with provider names, confidence scores, and last seen dates when available.

curl -X GET 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=2.56.188.34'

Response

1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 80,
5    "is_tor": false,
6    "is_proxy": true,
7    "proxy_provider_names": [
8      "Zyte Proxy"
9    ],
10    "proxy_confidence_score": 90,
11    "proxy_last_seen": "2025-12-12",
12    "is_residential_proxy": true,
13    "is_vpn": true,
14    "vpn_provider_names": [
15      "Nord VPN"
16    ],
17    "vpn_confidence_score": 99,
18    "vpn_last_seen": "2026-01-19",
19    "is_relay": false,
20    "relay_provider_name": "",
21    "is_anonymous": true,
22    "is_known_attacker": true,
23    "is_bot": false,
24    "is_spam": false,
25    "is_cloud_provider": true,
26    "cloud_provider_name": "Packethub S.A."
27  }
28}

Additional Query Parameters

Use these query parameters to exclude fields, or return only the fields you need.

1.Exclude Fields ( `excludes` )

Use excludes to remove fields you don’t need from the response. Pass a comma-separated list of field paths.

How to write field paths: Use dot notation for nested fields: object.field . For example:

Exclude specific flags: security.is_tor , security.is_cloud_provider

Note

ip is always included and cannot be excluded.

An example request and response are shown below.

curl -X GET 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=2.56.188.34&excludes=security.is_tor,security.is_cloud_provider'

Response

1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 80,
5    "is_proxy": true,
6    "proxy_provider_names": [
7      "Zyte Proxy"
8    ],
9    "proxy_confidence_score": 90,
10    "proxy_last_seen": "2025-12-12",
11    "is_residential_proxy": true,
12    "is_vpn": true,
13    "vpn_provider_names": [
14      "Nord VPN"
15    ],
16    "vpn_confidence_score": 99,
17    "vpn_last_seen": "2026-01-19",
18    "is_relay": false,
19    "relay_provider_name": "",
20    "is_anonymous": true,
21    "is_known_attacker": true,
22    "is_bot": false,
23    "is_spam": false,
24    "cloud_provider_name": "Packethub S.A."
25  }
26}

In this example, the response does not contain is_tor and is_cloud_provider in the security object.

2.Return Specific Fields ( `fields` )

Use fields to return only the response fields you need. This helps reduce response size and keeps the payload focused.

How to specify fields: Provide a comma-separated list using dot notation: object.field . For example:

Security score: security.threat_score

An example request and response are shown below.

curl -X GET 'https://api.ipgeolocation.io/v3/security?apiKey=API_KEY&ip=2.56.188.34&fields=security.threat_score'

Response

1{
2  "ip": "2.56.188.34",
3  "security": {
4    "threat_score": 80
5  }
6}

Bulk IP Security Lookup Endpoint

Use this endpoint to assess IP risk for large lists of IP addresses in a single request (up to 50,000 IPs per request).

The bulk lookup supports the same query parameters as the single lookup, so you can use excludes and fields to control the response.

In the response, each IP is returned with its own security result. This makes it easy to process results in batches for signups, log analysis, fraud checks, and monitoring workflows.

An example request and response are shown below.

curl -X POST 'https://api.ipgeolocation.io/v3/security-bulk?apiKey=API_KEY' \
-H 'Content-Type: application/json' \
-d '{"ips":["2.56.188.34","2.56.188.35"]}'

Response

1[
2  {
3    "ip": "2.56.188.34",
4    "security": {
5      "threat_score": 80,
6      "is_tor": false,
7      "is_proxy": true,
8      "proxy_provider_names": [
9        "Zyte Proxy"
10      ],
11      "proxy_confidence_score": 90,
12      "proxy_last_seen": "2025-12-12",
13      "is_residential_proxy": true,
14      "is_vpn": true,
15      "vpn_provider_names": [
16        "Nord VPN"
17      ],
18      "vpn_confidence_score": 99,
19      "vpn_last_seen": "2026-01-19",
20      "is_relay": false,
21      "relay_provider_name": "",
22      "is_anonymous": true,
23      "is_known_attacker": true,
24      "is_bot": false,
25      "is_spam": false,
26      "is_cloud_provider": true,
27      "cloud_provider_name": "Packethub S.A."
28    }
29  },
30  {
31    "ip": "2.56.188.35",
32    "security": {
33      "threat_score": 80,
34      "is_tor": false,
35      "is_proxy": true,
36      "proxy_provider_names": [
37        "Zyte Proxy"
38      ],
39      "proxy_confidence_score": 90,
40      "proxy_last_seen": "2025-11-07",
41      "is_residential_proxy": true,
42      "is_vpn": false,
43      "vpn_provider_names": [],
44      "vpn_confidence_score": 0,
45      "vpn_last_seen": "",
46      "is_relay": false,
47      "relay_provider_name": "",
48      "is_anonymous": true,
49      "is_known_attacker": true,
50      "is_bot": false,
51      "is_spam": false,
52      "is_cloud_provider": true,
53      "cloud_provider_name": "Packethub S.A."
54    }
55  }
56]

Note

Quota and billing: In bulk lookup, 2 Credits are charged for each valid IP address in the payload. Bogon, private, or malformed IPs are not counted.

Reference to IP Security API Response

Below, we provide separate tables for each JSON object in the response, listing all possible fields available across the security endpoint.

1.Standalone fields reference

Field	Type	Description	Can be empty?
ip	string	IP address that is used to lookup security information.	No

2. `security` json object reference

Field	Type	Description	Can be empty?
threat_score	number	Overall threat score for the IP address. Ranges from 0 to 100. 100 indicates the highest risk.	No
is_tor	boolean	Indicates whether the IP is a Tor exit node.	No
is_proxy	boolean	Indicates whether the IP is associated with a proxy network.	No
proxy_provider_names	array[string]	List of detected proxy provider names, when available.	Yes
proxy_confidence_score	number	Confidence score (0–100) for proxy detection, when flag is true. Defaults to 0.	No
proxy_last_seen	string	Last seen date (YYYY-MM-DD) for proxy activity, when available.	Yes
is_residential_proxy	boolean	Indicates whether the IP is associated with a residential proxy network.	No
is_vpn	boolean	Indicates whether the IP is associated with a VPN network.	No
vpn_provider_names	array[string]	List of detected VPN provider names, when available.	Yes
vpn_confidence_score	number	Confidence score (0–100) for VPN detection, when flag is true. Defaults to 0.	No
vpn_last_seen	string	Last seen date (YYYY-MM-DD) for VPN activity, when available.	Yes
is_relay	boolean	Indicates whether the IP is associated with a relay network.	No
relay_provider_name	string	Relay provider name, when available.	Yes
is_anonymous	boolean	Indicates whether the IP is anonymous. True if VPN, proxy, Tor, or relay is detected.	No
is_known_attacker	boolean	Indicates whether the IP is flagged for known attacker behavior.	No
is_bot	boolean	Indicates whether the IP is associated with bot activity.	No
is_spam	boolean	Indicates whether the IP is associated with spam activity.	No
is_cloud_provider	boolean	Indicates whether the IP belongs to a cloud provider.	No
cloud_provider_name	string	Name of the Cloud Provider, if the IP address belongs to a cloud provider.	Yes

Error Codes

IP Security API returns HTTP status code 200 for a successful API request along with the response.

While, in case of a bad or invalid request, IP Security API returns 4xx HTTP status code along with a descriptive message explaining the reason for the error.

Below is a detailed explanation of the specific HTTP status codes and their corresponding error conditions:

HTTP Status	Description
400 Bad Request	It is returned for one of the following reasons: If the provided IPv4 or IPv6 address is invalid. If special character(s) ( ) [ ] { } \| ^ ` is passed in the API URL either as parameter or its value. Specially in case of API key. If the IP addresses JSON list is empty, or the provided JSON does not have 'ips' field while querying `security-bulk` endpoint. If more than 50,000 IP addresses are provided while querying from `security-bulk` endpoint.
401 Unauthorized	It is returned for one of the following reasons: If API key (as `apiKey` URL parameter) is missing from the request to IP Security API. If an invalid (a random value) API key is provided. If the API request is made from an unverified ipgeolocation.io account. If your account has been disabled or locked to use by the admin due to abuse or illegal activity. When the request to IP Security API is made using API key for a database subscription When the request to IP Security API is made on the 'paused' subscription. If you’re making API requests after your subscription trial has been expired. If your active until date has passed and you need to upgrade your account. If bulk IP to security look-ups endpoint is called using free subscription API key.
404 Not Found	It is returned for one of the following reasons: If the IPv4 or IPv6 address does not exist in our database. If the IPv4 or IPv6 is passed as a path variable, instead of url parameter as `ip=` . If the wrong endpoint is called, that does not exist in our API.
405 Method Not Allowed	If wrong HTTP request method is used for calling the endpoints. Only GET and POST methods are allowed. POST method for `security-bulk` endpoint and GET method for `security` endpoint requests.
413 Content Too Large	If the passed data in the POST requests is more than the limit of the API.
415 Unsupported Media Type	If the payload for IPs in `security-bulk` endpoint is missing, or the content type is not mentioned as JSON.
423 Locked	If the passed IP address is from a bogon ip ranges, or is part of a private network.
429 Too Many Requests	It is returned for one of the following reasons: If the API usage limit has reached for the free subscriptions, or paid subscriptions with the status 'past due', 'deleted' or 'trial expired'. If the surcharge API usage limit has reached against the subscribed plan.
499 Client Closed Request	If the client has set the very short request or connection timeout, leading to the server closing the request prematurely.
5XX Server Side Error	If a `500` (Internal Server Error), `502` (Bad Gateway), `503` (Service Unavailable), `504` (Gateway Timeout), or `505` (HTTP Version Not Supported) status code is returned, it indicates an issue on our end. Please contact us with your request at support@ipgeolocation.io for further assistance.

API SDKs

To facilitate the developers, we have added some SDKs for various programming languages. The detailed documentation on how to use these SDKs is available in the respective SDK's documentation page linked below.

Our SDKs are also available on Github. Feel free to help us improve them. Following are the available SDKs:

Frequently Asked Questions

Each Security lookup costs 2 credits per valid IP. The X-Credits-Charged response header shows the total credits charged for the request. For details, please refer to our Credits Usage Guide.

In bulk lookup, 2 credits are charged for each valid IP in the payload. Bogon, private, or malformed IPs are not counted. The X-Credits-Charged response header shows the total credits charged for the request. For details, please refer to our Credits Usage Guide.

A confidence score is a 0–100 indicator of how strongly a signal (for example, VPN or proxy) is detected.

A score of 0 is the default value when the related detection flag is false.

Please use the Threat Score as a quick way to route traffic, and then use the flags to understand why. Each team uses the score differently depending on the product and the risk level of the action. For example, is_anonymous can be true when is_proxy or is_tor is true. If is_proxy is true, the IP is using a proxy route, which can be a commercial or residential proxy, and that can be determined by the is_residential_proxy flag. Use the separate flags to know what else it is: is_vpn, is_residential_proxy, or is_relay. Use these details to decide when to allow, challenge, restrict, or block, especially for sensitive actions.

is_anonymous indicates that the connection is using an anonymizing route such as a VPN, proxy, relay, or Tor. Many teams use it as a quick signal to apply extra verification on sensitive endpoints.

A relay is a privacy-focused routing service that can mask the original IP, similar to how a VPN or proxy hides location. Relays are often used for privacy and tracking protection, and they can also be used to bypass controls.

Proxy: Forwards traffic through another server and mainly masks the IP.
VPN: Routes traffic through a remote server and encrypts and tunnels the connection.
Tor: Routes traffic through multiple nodes to provide stronger anonymity.

Our security data is updated at least twice every 24 hours to capture changes across IP ranges. Downloadable security databases are available with daily and weekly update options, depending on your plan. Please see the Security Databases documentation for update details.

We refresh security data regularly and track VPNs, proxies, relays, and Tor exit nodes as providers add and rotate IP ranges. Like any IP-based detection, results can change over time, so we recommend monitoring outcomes and tuning your policy based on real traffic.

Our Security data is available on all paid plans. See our pricing page for details. We charge 2 credits per valid IP lookup for the Security data. If you include Security data in the /ipgeo endpoint, an additional 2 credits will be charged. The X-Credits-Charged response header shows the total credits charged for the request. To understand credits in detail, please refer to Credits Usage Guide.

Yes. Along with the Threat Score, the API returns flags such as VPN or proxy usage, relay signals, Tor, bot activity, spam indicators, known attacker signals, and cloud hosting context. These fields help you understand what was detected and support auditing and logging.

Tor is a privacy network that routes traffic through multiple nodes to make tracking harder. A Tor exit node is the last node that reaches the public internet, so websites typically see the exit node IP instead of the user’s real IP.

Yes. The API detects free and paid VPNs, commercial and residential proxies, privacy relays, and Tor exit nodes. It also returns related risk signals such as bot indicators, spam signals, known attacker flags, and anonymity status.

No. We do not flag well-known search engine crawlers and other clean bots as bots. The is_bot field is intended to indicate suspicious or abusive automation, so if you use is_bot in your rules, legitimate crawlers should not be blocked.

Yes. A free trial is available so you can test accuracy and integration. Please contact us via customer support or use the live chat on our website to request access.

Yes. You can download sample VPN and proxy data that includes the same risk flags returned by this API, so you can review the structure and quality. Please see Security Databases for examples and formats, or contact support if you want help choosing the right dataset or if you want data for your own IP ranges.

IP Security API

Overview

IP Security API Lookup Endpoints

Single IP Lookup Endpoint

1.Lookup the caller IP (no ip parameter)

2.Lookup a specific IP address

Additional Query Parameters

1.Exclude Fields ( excludes )

2.Return Specific Fields ( fields )

Bulk IP Security Lookup Endpoint

Reference to IP Security API Response

1.Standalone fields reference

2. security json object reference

Error Codes

API SDKs

Frequently Asked Questions

Subscribe Our Newsletter

1.Lookup the caller IP (no `ip` parameter)

1.Exclude Fields ( `excludes` )

2.Return Specific Fields ( `fields` )

2. `security` json object reference