AbuseIPDB - IP reputation check - 2026
AbuseIPDB is a centralized IP reputation database designed for collecting, storing, and serving information about malicious activity associated with IPv4 and IPv6 addresses. The service allows system administrators, webmasters, and information security professionals to check IP addresses for involvement in attacks, spam, port scanning, and other forms of abuse, as well as to submit reports about observed malicious activity. The project is built on a crowdsourcing model: the community collects and verifies data, forming a global knowledge base of threats.
History and purpose
AbuseIPDB was created in response to the need for a simple, open, and accessible tool for real-time IP reputation checking. Unlike commercial closed databases, AbuseIPDB offers a free entry tier with the ability to scale through paid subscriptions.
The main goals of the service:
- providing an API for automated IP address reputation checks;
- collecting reports from community members about malicious activity;
- generating a confidence score — a non-binary assessment of the likelihood that an address is malicious;
- integration with intrusion detection systems, primarily Fail2Ban.
API v2
AbuseIPDB provides a REST API version 2 (v2), which is the primary way to interact with the database programmatically. The API supports JSON and plaintext formats, using HTTP GET, POST, and DELETE methods.
Authentication
Access to the API requires an API key, which is issued after registering an account on the website. The key is passed in the HTTP header:
-H "Key: YOUR_OWN_API_KEY"
It is also possible to pass the key as a query parameter key, but using the header is the recommended approach.
Endpoints
API v2 includes seven main endpoints:
CHECK endpoint
The GET /api/v2/check endpoint accepts a single IP address (IPv4 or IPv6) and returns comprehensive reputation information.
curl -G https://api.abuseipdb.com/api/v2/check \ --data-urlencode "ipAddress=118.25.6.39" \ -d maxAgeInDays=90 \ -d verbose \ -H "Key: YOUR_OWN_API_KEY" \ -H "Accept: application/json"
Request parameters:
| Field | Required | Default | Description |
|---|---|---|---|
| ipAddress | Yes | — | IPv4 or IPv6 address to check |
| maxAgeInDays | No | 30 | Maximum age of reports in days (1–365) |
| verbose | No | false | When set, returns full reports with comments |
Example response:
{
"data": {
"ipAddress": "118.25.6.39",
"isPublic": true,
"ipVersion": 4,
"isWhitelisted": false,
"abuseConfidenceScore": 100,
"countryCode": "CN",
"countryName": "China",
"usageType": "Data Center/Web Hosting/Transit",
"isp": "Tencent Cloud Computing (Beijing) Co. Ltd",
"domain": "tencent.com",
"hostnames": [],
"isTor": false,
"totalReports": 1,
"numDistinctUsers": 1,
"lastReportedAt": "2018-12-20T20:55:14+00:00",
"reports": [
{
"reportedAt": "2018-12-20T20:55:14+00:00",
"comment": "Invalid user oracle from 118.25.6.39",
"categories": [18, 22],
"reporterId": 1,
"reporterCountryCode": "US",
"reporterCountryName": "United States"
}
]
}
}
The abuseConfidenceScore field (0–100) is the key reputation indicator: the higher the value, the more likely the IP address is used for malicious activity. The isWhitelisted field indicates whether the address appears in AbuseIPDB whitelists, but the developers recommend relying on the confidence score as a more nuanced tool.
Possible values for the usageType field:
- Commercial
- Organization
- Government
- Military
- University/College/School
- Library
- Content Delivery Network
- Fixed Line ISP
- Mobile ISP
- Data Center/Web Hosting/Transit
- Search Engine Spider
- Reserved
REPORTS endpoint
The GET /api/v2/reports endpoint returns a paginated list of reports for a given IP address.
curl -G https://api.abuseipdb.com/api/v2/reports \ --data-urlencode "ipAddress=176.111.173.242" \ -d page=5 \ -d perPage=25 \ -H "Key: YOUR_OWN_API_KEY" \ -H "Accept: application/json"
Request parameters:
| Field | Required | Default | Description |
|---|---|---|---|
| ipAddress | Yes | — | IPv4 or IPv6 address |
| maxAgeInDays | No | 30 | Maximum age of reports |
| page | No | 1 | Page number |
| perPage | No | 25 | Records per page (max 200) |
The response includes fields: total, page, perPage, lastPage, nextPageUrl, previousPageUrl, and a results array with the details of each report.
BLACKLIST endpoint
The GET /api/v2/blacklist endpoint allows downloading a list of IP addresses filtered by a minimum confidence level.
curl -G https://api.abuseipdb.com/api/v2/blacklist \ -d confidenceMinimum=90 \ -H "Key: YOUR_OWN_API_KEY" \ -H "Accept: application/json"
It supports plaintext output (plaintext parameter), filtering by country (countryCode), IP version (ipVersion), and limiting the number of records (limit). For paid subscriptions, the number of IPs in the output can be configured up to 100,000–500,000.
REPORT endpoint
The POST /api/v2/report endpoint is used to submit a report about a malicious IP address.
curl https://api.abuseipdb.com/api/v2/report \ -H "Accept: application/json" \ -H "Key: YOUR_OWN_API_KEY" \ --data-urlencode "ip=118.25.6.39" \ --data-urlencode "comment=SSH brute-force attack detected" \ -d "categories=18,22"
Parameters:
| Field | Required | Description |
|---|---|---|
| ip | Yes | IPv4 or IPv6 address |
| categories | Yes | Comma-separated list of category IDs |
| comment | No | Comment describing the activity |
Abuse categories (IDs 1–23):
| ID | Title | Description |
|---|---|---|
| 1 | DNS Compromise | Altering DNS records resulting in improper redirection |
| 2 | DNS Poisoning | Falsifying domain server cache (cache poisoning) |
| 3 | Fraud Orders | Fraudulent orders |
| 4 | DDoS Attack | Participating in distributed denial-of-service (usually part of botnet) |
| 5 | FTP Brute-Force | FTP password brute-forcing |
| 6 | Ping of Death | Oversized IP packet |
| 7 | Phishing | Phishing websites and/or email |
| 8 | Fraud VoIP | Fraudulent VoIP activity |
| 9 | Open Proxy | Open proxy, open relay, or Tor exit node |
| 10 | Web Spam | Spam in web forums/comments |
| 11 | Email Spam | Spam via email |
| 12 | Blog Spam | Spam in blogs |
| 13 | VPN IP | VPN server IP address |
| 14 | Port Scan | Scanning for open ports and vulnerable services |
| 15 | Hacking | Attempted hacking |
| 16 | SQL Injection | SQL injection attacks |
| 17 | Spoofing | Sender spoofing |
| 18 | Brute-Force | Credential brute-force attacks on SSH, FTP, SIP, SMTP, RDP, and web logins |
| 19 | Bad Web Bot | Malicious web bots |
| 20 | Exploited Host | Compromised host |
| 21 | Web App Attack | Web application attacks |
| 22 | SSH Abuse | SSH abuse |
| 23 | IoT Targeted | Attacks targeting IoT devices |
CHECK-BLOCK endpoint
The GET /api/v2/check-block endpoint accepts a subnet in CIDR notation and returns aggregated data for all IPs in the specified range.
curl -G https://api.abuseipdb.com/api/v2/check-block \ --data-urlencode "network=127.0.0.1/24" \ -d maxAgeInDays=15 \ -H "Key: YOUR_OWN_API_KEY" \ -H "Accept: application/json"
The maximum network size depends on the plan tier:
| Parameter | Free | Basic | Premium |
|---|---|---|---|
| network | up to /2 | up to /20 | up to /16 |
| maxAgeInDays | up to 30 | up to 60 | up to 365 |
BULK-REPORT endpoint
The POST /api/v2/bulk-report endpoint allows uploading a CSV file with multiple IP addresses for simultaneous reporting.
curl https://api.abuseipdb.com/api/v2/bulk-report \ -F csv=@report.csv \ -H "Key: YOUR_OWN_API_KEY" \ -H "Accept: application/json" \ > output.json
CSV format: each row contains the IP, categories, and an optional comment.
CLEAR-ADDRESS endpoint
The DELETE /api/v2/clear-address endpoint allows removing all of your own past reports for a given IP address.
curl -X DELETE https://api.abuseipdb.com/api/v2/clear-address \ --data-urlencode "ipAddress=118.25.6.39" \ -H "Key: YOUR_OWN_API_KEY" \ -H "Accept: application/json"
The response returns the number of deleted reports.
Rate limits and pricing plans
The API has daily limits on the number of requests to each endpoint. Limits vary by account type.
| Endpoint | Free | Webmaster | Supporter | Basic ($25/mo) | Premium ($99/mo) |
|---|---|---|---|---|---|
| check | 1,000 | 3,000 | 5,000 | 10,000 | 50,000 |
| reports | 100 | 500 | 1,000 | 5,000 | 25,000 |
| blacklist | 5 | 10 | 20 | 100 | 500 |
| report | 1,000 | 3,000 | 1,000 | 10,000 | 50,000 |
| check-block | 100 | 250 | 500 | 1,000 | 5,000 |
| bulk-report | 5 | 10 | 20 | 100 | 500 |
| clear-address | 5 | 10 | 20 | 100 | 500 |
When the daily limit is exceeded, the API returns HTTP status 429 Too Many Requests. The free account provides 1,000 checks and reports per day forever. All paid plans include a 30-day free trial.
Error handling
The API returns standard HTTP status codes:
- 200 — successful request;
- 401 — unauthorized (invalid or missing API key);
- 402 — parameter limit exceeded (e.g., subnet too large for CHECK-BLOCK);
- 422 — unprocessable entity (invalid parameters);
- 429 — daily rate limit exceeded.
Error response structure:
{
"errors": [
{
"detail": "Error description",
"status": 422
}
]
}
Fail2Ban integration
AbuseIPDB has built-in integration with Fail2Ban — a popular intrusion prevention system. The Fail2Ban distribution includes an abuseipdb.conf configuration file that allows automatic reporting to AbuseIPDB when a ban action is triggered.
Example actionban configuration for Fail2Ban:
actionban = curl --fail 'https://api.abuseipdb.com/api/v2/report' \
-H 'Accept: application/json' \
-H 'Key: YOUR_ABUSEIPDB_API_KEY' \
--data-urlencode 'comment=<matches>' \
--data-urlencode 'ip=<ip>' \
--data 'categories=18,22'
When migrating from API v1 to v2, note that:
- the category parameter has been renamed to categories;
- the API key should preferably be passed via the HTTP header;
- IPv6 addresses must be URL-encoded because they contain colons;
- the request must include the Accept: application/json header.
Security and CORS
The API supports Cross-Origin Resource Sharing (CORS), allowing direct requests from browsers when developing client-side applications. Passing the API key via request headers ensures protection against interception on public networks.
Summary
AbuseIPDB is a mature and feature-rich IP reputation checking service built on a crowdsourced data collection model. API v2 covers all major use cases: checking individual addresses and subnets, retrieving report lists, downloading blacklists, submitting reports (including bulk), and managing your own data. The availability of a free tier, Fail2Ban integration, and a flexible category system make AbuseIPDB one of the most accessible and practical tools for the daily work of an information security professional.
Links
- https://www.abuseipdb.com/ — Official website
- https://docs.abuseipdb.com/ — API v2 documentation
- https://www.abuseipdb.com/categories — Report categories
- https://www.abuseipdb.com/pricing — Pricing plans
- https://www.abuseipdb.com/fail2ban.html — Fail2Ban integration
- https://www.abuseipdb.com/account/api — Get an API key
