Subnet Lookup

Look up threat intelligence for all IPs within a subnet range using CIDR notation.

Endpoint

GET https://ipswamp.com/api/v1/checkSubnet

Request

Headers

Header	Required	Description
Authorization	Yes*	Bearer <api-key>
X-API-Key	Yes*	Alternative to Authorization header

INFO

One of Authorization or X-API-Key is required.

Query Parameters

Parameter	Type	Required	Description
cidr	string	Yes	CIDR notation of the subnet to scan (e.g., 1.2.3.0/24)

WARNING

The maximum supported subnet size is /24 (256 IP addresses). Larger subnets will return a 400 error.

Response

Success (200)

Returns threat intelligence data for each IP in the subnet along with a summary.

{
  "cidr": "1.2.3.0/24",
  "network": "1.2.3.0",
  "broadcast": "1.2.3.255",
  "total_ips": 254,
  "results": [
    {
      "ip": "1.2.3.1",
      "threat_score": 85,
      "threat_level": "CRITICAL",
      "last_attack": "2026-04-15T10:30:00.000Z",
      "ip_rep": "known attacker",
      "total_hits": 142
    },
    {
      "ip": "1.2.3.2",
      "threat_score": 0,
      "threat_level": "LOW",
      "last_attack": null,
      "ip_rep": "clean",
      "total_hits": 0
    }
  ],
  "summary": {
    "total": 254,
    "malicious": 3,
    "clean": 251,
    "average_score": 1.2,
    "found_count": 3
  }
}

Response Fields

Field	Type	Description
cidr	string	The requested CIDR range
network	string	The network address of the subnet
broadcast	string	The broadcast address of the subnet
total_ips	number	Total number of usable IPs (excluding network/broadcast)
results	array	Array of IP results found in the threat database
summary	object	Aggregated statistics for the subnet

INFO

The results array only includes IPs found in the threat database. IPs with no threat data are not included in the results.

Result Object

Field	Type	Description
ip	string	The IP address
threat_score	number	Threat score from 0 to 100
threat_level	string	Severity bucket: LOW, MEDIUM, HIGH, CRITICAL
last_attack	string	ISO timestamp of last detected attack
ip_rep	string	Reputation classification
total_hits	number	Total number of malicious hits recorded

Summary Object

Field	Type	Description
total	number	Total usable IPs in the subnet
malicious	number	Number of IPs with threat data
clean	number	Number of IPs without threat data
average_score	number	Average threat score across found IPs
found_count	number	Number of IPs found in the threat database

Error Responses

Status	Response	Description
400	{ "error": true, "statusCode": 400, "message": "CIDR is required" }	Missing CIDR parameter
400	{ "error": true, "statusCode": 400, "message": "Invalid CIDR format" }	Malformed CIDR notation
400	{ "error": true, "statusCode": 400, "message": "Maximum /24 subnet size" }	Subnet too large
401	{ "error": true, "statusCode": 401, "message": "API key required..." }	No API key provided
403	{ "error": true, "statusCode": 403, "message": "Invalid API key" }	Invalid or expired API key
429	{ "error": true, "statusCode": 429, "message": "Rate limit exceeded" }	Too many requests
500	{ "error": true, "statusCode": 500, "message": "Internal server error" }	Server error

Quota

Each IP found in the threat database counts as 1 toward your usage quota. IPs without threat data do not count.

Examples

Basic Request

curl -X GET "https://ipswamp.com/api/v1/checkSubnet?cidr=1.2.3.0/24" \
  -H "Authorization: Bearer your-api-key-here"

Using X-API-Key Header

curl -X GET "https://ipswamp.com/api/v1/checkSubnet?cidr=1.2.3.0/24" \
  -H "X-API-Key: your-api-key-here"

JavaScript/TypeScript

const cidr = "1.2.3.0/24";
const response = await fetch(
  `https://ipswamp.com/api/v1/checkSubnet?cidr=${encodeURIComponent(cidr)}`,
  {
    headers: {
      Authorization: "Bearer your-api-key-here",
    },
  },
);

const data = await response.json();
console.log(
  `Subnet ${data.cidr}: ${data.summary.malicious} malicious IPs out of ${data.summary.total}`
);

Python

import requests

url = "https://ipswamp.com/api/v1/checkSubnet"
params = {"cidr": "1.2.3.0/24"}
headers = {
    "Authorization": "Bearer your-api-key-here"
}

response = requests.get(url, params=params, headers=headers)
data = response.json()

print(f"Subnet {data['cidr']}: "
      f"{data['summary']['malicious']} malicious IPs out of {data['summary']['total']}")

See Also

• Check IP Address — Single IP lookup
• Bulk IP Lookup — Multiple IP lookup
• IP Export — Export threat data