---
title: "Developer Docs for VPN & Proxy Detection API | IP Security API"
slug: "/documentation/ip-security-api.html"
parent: "IP Geolocation API"
description: "Detect VPN, proxy, hosting, relay, and bot traffic using IPGeolocation.io’s IP Security API. Full Docs, response fields, error codes, auth, and code examples."
---

# 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**. The `X-Credits-Charged` response header shows the total credits charged for the request. For details, please refer to our [Credits Usage Guide](https://ipgeolocation.io/documentation/credits-usage.html).

* * *

## 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 Preview**

```json
{
  "ip": "115.186.118.130",
  "security": {
    "threat_score": 0,
    "is_tor": false,
    "is_proxy": false,
    "proxy_provider_names": [],
    "proxy_confidence_score": 0,
    "proxy_last_seen": "",
    "is_residential_proxy": false,
    "is_vpn": false,
    "vpn_provider_names": [],
    "vpn_confidence_score": 0,
    "vpn_last_seen": "",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": false,
    "is_known_attacker": false,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": false,
    "cloud_provider_name": ""
  }
}
```

* * *

### 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 Preview**

```json
{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": [
      "Zyte Proxy"
    ],
    "proxy_confidence_score": 80,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": [
      "Nord VPN"
    ],
    "vpn_confidence_score": 80,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A."
  }
}
```

* * *

## 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 Preview**

```json
{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80,
    "is_proxy": true,
    "proxy_provider_names": [
      "Zyte Proxy"
    ],
    "proxy_confidence_score": 80,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": [
      "Nord VPN"
    ],
    "vpn_confidence_score": 80,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "cloud_provider_name": "Packethub S.A."
  }
}
```

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 Preview**

```json
{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80
  }
}
```

* * *

## Bulk IP Security Lookup Endpoint

The bulk endpoint allows you to perform IP security lookup for multiple IPv4 or IPv6 (maximum **50,000**) in a single request.

*   Bulk lookup supports the same query parameters as the single lookup ( `excludes` , `fields` , and `output` ).

> [!IMPORTANT]
> - For bulk lookups, the requests count and quota billing are calculated per **valid** IP address or domain name submitted, using the same credit rules as single lookups (**+2** for Security); bogon, private, and malformed IPs are not counted, and the exact charge is returned in the `X-Credits-Charged` response header.
> - The `X-Successful-Record` response header is returned **only if the request contains one or more invalid IP addresses**. It indicates how many entries returned valid data with an HTTP `200` status. If all submitted IPs or domains are valid, this header is not included in the response.

* * *

### 1. Bulk lookup request

Send a `POST` request and pass the `ips` array as JSON.

```
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 Preview**

```json
[
  {
    "ip": "2.56.188.34",
    "security": {
      "threat_score": 80,
      "is_tor": false,
      "is_proxy": true,
      "proxy_provider_names": [
        "Zyte Proxy"
      ],
      "proxy_confidence_score": 80,
      "proxy_last_seen": "2025-12-12",
      "is_residential_proxy": true,
      "is_vpn": true,
      "vpn_provider_names": [
        "Nord VPN"
      ],
      "vpn_confidence_score": 80,
      "vpn_last_seen": "2026-01-19",
      "is_relay": false,
      "relay_provider_name": "",
      "is_anonymous": true,
      "is_known_attacker": true,
      "is_bot": false,
      "is_spam": false,
      "is_cloud_provider": true,
      "cloud_provider_name": "Packethub S.A."
    }
  },
  {
    "ip": "2.56.188.35",
    "security": {
      "threat_score": 35,
      "is_tor": false,
      "is_proxy": false,
      "proxy_provider_names": [],
      "proxy_confidence_score": 0,
      "proxy_last_seen": "",
      "is_residential_proxy": false,
      "is_vpn": false,
      "vpn_provider_names": [],
      "vpn_confidence_score": 0,
      "vpn_last_seen": "",
      "is_relay": false,
      "relay_provider_name": "",
      "is_anonymous": false,
      "is_known_attacker": true,
      "is_bot": false,
      "is_spam": false,
      "is_cloud_provider": true,
      "cloud_provider_name": "Packethub S.A."
    }
  }
]
```

* * *

### 2. Bulk Lookup with Additional Request Parameters

Use `fields` when you want to return only specific properties from the `security` object. Use `excludes` when you want to return the full `security` object but omit certain properties.

#### I. Using fields Parameter

This example uses the `fields` parameter to return only specific fields from the `security` object.

The goal is to return only:

*   `security.is_vpn`
*   `security.vpn_confidence_score`
*   `security.is_proxy`

Here is how the parameter is used:

*   Select only required fields: `fields=security.is_vpn,security.vpn_confidence_score,security.is_proxy`

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

**Response Preview**

```json
[
  {
    "ip": "2.56.188.34",
    "security": {
      "is_proxy": true,
      "is_vpn": true,
      "vpn_confidence_score": 80
    }
  },
  {
    "ip": "2.56.188.35",
    "security": {
      "is_proxy": false,
      "is_vpn": false,
      "vpn_confidence_score": 0
    }
  }
]
```

#### II. Using excludes Parameter

This example uses the `excludes` parameter to remove specific fields from the `security` object.

The goal is to return the full `security` object except:

*   `security.threat_score`
*   `security.proxy_last_seen`
*   `security.vpn_last_seen`

Here is how the parameter is used:

*   Exclude specific fields: `excludes=security.threat_score,security.proxy_last_seen,security.vpn_last_seen`

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

**Response Preview**

```json
[
  {
    "ip": "2.56.188.34",
    "security": {
      "is_tor": false,
      "is_proxy": true,
      "proxy_provider_names": [
        "Zyte Proxy"
      ],
      "proxy_confidence_score": 80,
      "is_residential_proxy": true,
      "is_vpn": true,
      "vpn_provider_names": [
        "Nord VPN"
      ],
      "vpn_confidence_score": 80,
      "is_relay": false,
      "relay_provider_name": "",
      "is_anonymous": true,
      "is_known_attacker": true,
      "is_bot": false,
      "is_spam": false,
      "is_cloud_provider": true,
      "cloud_provider_name": "Packethub S.A."
    }
  },
  {
    "ip": "2.56.188.35",
    "security": {
      "is_tor": false,
      "is_proxy": false,
      "proxy_provider_names": [],
      "proxy_confidence_score": 0,
      "is_residential_proxy": false,
      "is_vpn": false,
      "vpn_provider_names": [],
      "vpn_confidence_score": 0,
      "is_relay": false,
      "relay_provider_name": "",
      "is_anonymous": false,
      "is_known_attacker": true,
      "is_bot": false,
      "is_spam": false,
      "is_cloud_provider": true,
      "cloud_provider_name": "Packethub S.A."
    }
  }
]
```

* * *

### 3. Bulk Lookup Response for Invalid IPs

In a bulk request, each IP address is processed independently.

If an IP address is invalid (non-public, non-routable, or malformed), the API returns an object containing only a descriptive `message` field for that entry along with the valid public IP address responses.

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

**Response Preview**

```json
[
  {
    "message": "'10.0.0.0' is a bogon IP address."
  },
  {
    "ip": "2.56.188.35",
    "security": {
      "threat_score": 35,
      "is_tor": false,
      "is_proxy": false,
      "proxy_provider_names": [],
      "proxy_confidence_score": 0,
      "proxy_last_seen": "",
      "is_residential_proxy": false,
      "is_vpn": false,
      "vpn_provider_names": [],
      "vpn_confidence_score": 0,
      "vpn_last_seen": "",
      "is_relay": false,
      "relay_provider_name": "",
      "is_anonymous": false,
      "is_known_attacker": true,
      "is_bot": false,
      "is_spam": false,
      "is_cloud_provider": true,
      "cloud_provider_name": "Packethub S.A."
    }
  }
]
```

* * *

## Security Details in Main IPGeolocation Endpoint

Security data is available only on the **Paid plan** of the **IP Geolocation API**. See the [Pricing page](https://ipgeolocation.io/pricing.html) for plan details.  
  
You can retrieve security details using the `/v3/ipgeo` endpoint by explicitly including `include=security` in the query parameters. When requested, the response includes security information along with location, abuse contact, timezone, ASN data, user-agent, network, company and other fields described in the [IP Geolocation API documentation](https://ipgeolocation.io/documentation/ip-location-api.html).  
  
Security details are returned in the `/v3/ipgeo` response once the `security` object is enabled, as shown below.

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

**Response Preview**

```json
{
  "ip": "2.56.188.34",
  "security": {
    "threat_score": 80,
    "is_tor": false,
    "is_proxy": true,
    "proxy_provider_names": [
      "Zyte Proxy"
    ],
    "proxy_confidence_score": 80,
    "proxy_last_seen": "2025-12-12",
    "is_residential_proxy": true,
    "is_vpn": true,
    "vpn_provider_names": [
      "Nord VPN"
    ],
    "vpn_confidence_score": 80,
    "vpn_last_seen": "2026-01-19",
    "is_relay": false,
    "relay_provider_name": "",
    "is_anonymous": true,
    "is_known_attacker": true,
    "is_bot": false,
    "is_spam": false,
    "is_cloud_provider": true,
    "cloud_provider_name": "Packethub S.A."
  },
  "location": {
    "continent_code": "NA",
    "continent_name": "North America",
    "country_code2": "US",
    "country_code3": "USA",
    "country_name": "United States",
    "country_name_official": "United States of America",
    "country_capital": "Washington, D.C.",
    "state_prov": "Texas",
    "state_code": "US-TX",
    "district": "Dallas",
    "city": "Dallas",
    "zipcode": "75201",
    "latitude": "32.77822",
    "longitude": "-96.79512",
    "is_eu": false,
    "country_flag": "https://ipgeolocation.io/static/flags/us_64.png",
    "geoname_id": "4684902",
    "country_emoji": "🇺🇸"
  },
  "country_metadata": {
    "calling_code": "+1",
    "tld": ".us",
    "languages": [
      "en-US",
      "es-US",
      "haw",
      "fr"
    ]
  },
  "network": {
    "connection_type": "",
    "route": "2.56.188.0/22",
    "is_anycast": false
  },
  "currency": {
    "code": "USD",
    "name": "US Dollar",
    "symbol": "$"
  },
  "asn": {
    "as_number": "AS62240",
    "organization": "Clouvider Limited",
    "country": "GB",
    "type": "HOSTING",
    "domain": "clouvider.net",
    "date_allocated": "2013-12-12",
    "rir": "RIPE"
  },
  "company": {
    "name": "Packethub S.A.",
    "type": "BUSINESS",
    "domain": "packethub.com"
  },
  "time_zone": {
    "name": "America/Chicago",
    "offset": -6,
    "offset_with_dst": -6,
    "current_time": "2026-03-07 03:37:38.628-0600",
    "current_time_unix": 1772876258.628,
    "current_tz_abbreviation": "CST",
    "current_tz_full_name": "Central Standard Time",
    "standard_tz_abbreviation": "CST",
    "standard_tz_full_name": "Central Standard Time",
    "is_dst": false,
    "dst_savings": 0,
    "dst_exists": true,
    "dst_tz_abbreviation": "CDT",
    "dst_tz_full_name": "Central Daylight Time",
    "dst_start": {
      "utc_time": "2026-03-08 TIME 08:00",
      "duration": "+1.00H",
      "gap": true,
      "date_time_after": "2026-03-08 TIME 03:00",
      "date_time_before": "2026-03-08 TIME 02:00",
      "overlap": false
    },
    "dst_end": {
      "utc_time": "2026-11-01 TIME 07:00",
      "duration": "-1.00H",
      "gap": false,
      "date_time_after": "2026-11-01 TIME 01:00",
      "date_time_before": "2026-11-01 TIME 02:00",
      "overlap": true
    }
  }
}
```

> [!IMPORTANT]
> The `security` object returned by `/v3/ipgeo` (when requested using `include=security` ) contains the same security data available through the dedicated `/v3/security` endpoint.  
>
> Use `/v3/ipgeo` when security information is required together with additional data such as location, ASN, abuse, timezone, company, network, or user-agent details within a single response.  
>
> When only security information is required, it is recommended to use the dedicated `/v3/security` endpoint to reduce response payload size and maintain more predictable credit usage.

* * *

## 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.

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 request payload is empty or missing, or the provided JSON does not contain the `ips` field, or the IP addresses JSON list is empty while querying the `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 your account has been disabled or locked to use 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 using a free subscription API key. * When the request to IP Security API is made on the 'paused' subscription. * If a domain name is passed in the `ip` parameter when making a request to the IP Security API. * If you're making API requests after your subscription trial has been expired. * If your account's active-until date has passed and you need to renew or upgrade your subscription. * If bulk IP to security lookup endpoint is called using free subscription API key. * If the bulk IP to security lookup endpoint is called using Request Origin (CORS) authentication. Bulk requests require an `apiKey` and cannot be authenticated using Request Origin. |
| 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, IPv6 or domain name 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 `Content-Type` header is not set to `application/json` , while sending a request to the `security-bulk` endpoint. |
| 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 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](mailto: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:

*   [IP Geolocation API Java SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-java-sdk.html)
*   [IP Geolocation API Python SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-python-sdk.html)
*   [IP Geolocation API Go SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-go-sdk.html)
*   [IP Geolocation API Ruby SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-ruby-sdk.html)
*   [IP Geolocation API C-Sharp dotNet SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-c-sharp-dotnet-sdk.html)
*   [IP Geolocation API Rust SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-rust-sdk.html)
*   [IP Geolocation API Kotlin SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-kotlin-sdk.html)
*   [IP Geolocation API Swift SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-swift-sdk.html)
*   [IP Geolocation API C++ SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-cpp-sdk.html)
*   [IP Geolocation API PHP SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-php-sdk.html)
*   [IP Geolocation API Typescript SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-typescript-sdk.html)
*   [IP Geolocation API Javascript SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-javascript-sdk.html)
*   [IP Geolocation API JQuery SDK](https://ipgeolocation.io/documentation/ip-geolocation-api-jquery-sdk.html)
*   [Astronomy API Javascript SDK](https://ipgeolocation.io/documentation/astronomy-api-sdk.html)

## Frequently Asked Questions

### How many credits does the Security API charge?

**Answer:** 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](https://ipgeolocation.io/documentation/credits-usage.html).

### How are credits counted in bulk lookups?

**Answer:** 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](https://ipgeolocation.io/documentation/credits-usage.html).

### What is a confidence score?

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

### Why is the confidence score sometimes 0?

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

### How should I use the Threat Score in my app?

**Answer:** 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.

### What does is_anonymous mean?

**Answer:** 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.

### What is Relay?

**Answer:** 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.

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

**Answer:**

*   **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.

### How frequently is the security data updated?

**Answer:** 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.

### How accurate is VPN and proxy detection?

**Answer:** 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.

### What is the starting price for the IP Security API?

**Answer:**

Our Security data is available on all paid plans. See our [pricing](https://ipgeolocation.io/pricing.html) 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](https://ipgeolocation.io/documentation/credits-usage.html).

### Does the response explain why an IP is risky?

**Answer:** 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.

### What is Tor, and what is a Tor exit node?

**Answer:** 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.

### Does the API detect residential proxies?

**Answer:** 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.

### Does the API block search engine bots like Googlebot?

**Answer:** 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.

### Do you offer a free trial to test accuracy and integration?

**Answer:** Yes. A free trial is available so you can test accuracy and integration. Please [contact](https://ipgeolocation.io/contact.html) us via customer support or use the live chat on our website to request access.

### Can I get sample data or a downloadable VPN and proxy database?

**Answer:** 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](https://ipgeolocation.io/security-pro-databases.html) for examples and formats, or [contact](https://ipgeolocation.io/contact.html) support if you want help choosing the right dataset or if you want data for your own IP ranges.

Looking for features, pricing, and use cases? Visit the IP Security API page.

[Explore IP Security API](https://ipgeolocation.io/ip-security-api.html)