---
title: Bulk IP Threat Intelligence API Reference
version: 1.0.0
description: Retrieve threat intelligence and security profiles for up to 50,000 IP addresses in a single request. Each entry in the response array includes a composite 0-100 threat score plus per-signal flags for VPN, proxy, residential proxy, Tor exit node, bot, spam, and known-attacker activity, along with confidence scores and provider names where available. Use the `fields` and `excludes` query parameters to control which security signals are returned, reducing payload size for bulk workflows. A bad or bogon IP in the batch returns a per-item error object instead of failing the entire request, so you can process mixed-validity inputs in one call.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 6
---

## Table of Contents

- [Bulk IP Threat Intelligence API Reference v1.0.0](#bulk-ip-threat-intelligence-api-reference-v100)
  - [Authentication](#authentication)
  - [IP Geolocation APIs](#ip-geolocation-apis)
    - [bulkIpSecurityLookup](#bulkipsecuritylookup)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [BulkIpSecurityRequest](#bulkipsecurityrequest)
    - [ErrorResponse](#errorresponse)
    - [BulkIpSecurityItemError](#bulkipsecurityitemerror)
    - [BulkIpSecurityResultItem](#bulkipsecurityresultitem)
    - [BulkIpSecurityResponse](#bulkipsecurityresponse)
    - [Security](#security)



# Bulk IP Threat Intelligence API Reference v1.0.0

Retrieve threat intelligence and security profiles for up to 50,000 IP addresses in a single request. Each entry in the response array includes a composite 0-100 threat score plus per-signal flags for VPN, proxy, residential proxy, Tor exit node, bot, spam, and known-attacker activity, along with confidence scores and provider names where available. Use the `fields` and `excludes` query parameters to control which security signals are returned, reducing payload size for bulk workflows. A bad or bogon IP in the batch returns a per-item error object instead of failing the entire request, so you can process mixed-validity inputs in one call.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## IP Geolocation APIs

### bulkIpSecurityLookup

`POST /ip/security`

*Retrieve threat intelligence data for multiple IP addresses in a single request*

Get security profiles including threat score, VPN, proxy, Tor, bot, and spam detection for up to 50,000 IPs per request. Each item in the response array corresponds to one requested IP; invalid or bogon IPs return a per-item error object.

> Body parameter

```json
{
  "ips": [
    "8.8.8.8",
    "1.1.1.1",
    "45.33.32.156"
  ]
}
```

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response.|
|fields|query|string|false|Comma-separated list of fields to return. Supports dot notation (e.g. security.threat_score).|
|excludes|query|string|false|Comma-separated list of fields to remove from the response. Supports dot notation (e.g. security.is_tor).|
|body|body|[BulkIpSecurityRequest](#bulkipsecurityrequest)|true|none|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|

> Example responses

> Successful threat intelligence response. The response array always contains one item for each input IP, preserving order; an IP that fails validation (invalid, bogon, reserved, or not found) yields an error item instead of a security result.

```json
[
  {
    "ip": "8.8.8.8",
    "security": {
      "threat_score": 5,
      "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": true,
      "cloud_provider_name": "Google LLC"
    }
  },
  {
    "ip": "1.1.1.1",
    "security": {
      "threat_score": 5,
      "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": true,
      "cloud_provider_name": "Cloudflare, Inc."
    }
  }
]
```

```json
[
  {
    "message": "Provided IP address 'not-an-ip' is not valid"
  },
  {
    "ip": "8.8.8.8",
    "security": {
      "threat_score": 5,
      "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": true,
      "cloud_provider_name": "Google LLC"
    }
  }
]
```

```json
[
  {
    "message": "'127.0.0.1' is a bogon IP address."
  }
]
```

> Bad Request - Missing, empty, or malformed request body

```json
{
  "error": "Invalid request body Exception",
  "message": "Please provide data in required format in request body",
  "path": "/v1.0/ip/security",
  "status": 400,
  "timestamp": "2026-07-22T14:03:26.577Z"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful threat intelligence response. The response array always contains one item for each input IP, preserving order; an IP that fails validation (invalid, bogon, reserved, or not found) yields an error item instead of a security result.|[BulkIpSecurityResponse](#bulkipsecurityresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request - Missing, empty, or malformed request body|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### BulkIpSecurityRequest

Request body for bulk IP threat intelligence lookup.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|ips|[string]|true|none|List of 1–50,000 IPv4 and/or IPv6 addresses to look up for threat intelligence data.|

### ErrorResponse

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|

### BulkIpSecurityItemError

Per-item error, returned in place of a security result when an individual IP is invalid, bogon/reserved, or not found in the database.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|message|string|true|none|Human-readable reason this IP could not be resolved.|

### BulkIpSecurityResultItem

Threat intelligence result for one successfully resolved IP address.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|ip|string|true|none|The IP address used for the lookup (IPv4 or IPv6).|
|security|[Security](#security)|true|none|Threat intelligence and security information for the IP.|

### BulkIpSecurityResponse

Array of per-IP results, one entry per requested IP, in the same order as the request. Each entry is either a security result or, if that IP could not be resolved, an error object.

#### Properties

oneOf

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[BulkIpSecurityResultItem](#bulkipsecurityresultitem)|false|none|Threat intelligence result for one successfully resolved IP address.|

xor

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|*anonymous*|[BulkIpSecurityItemError](#bulkipsecurityitemerror)|false|none|Per-item error, returned in place of a security result when an individual IP is invalid, bogon/reserved, or not found in the database.|

### Security

Threat intelligence and security information for the IP.

#### Properties

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