IPRisk IPRisk
ZH|EN
API v1

IP Cleanliness API

Use one endpoint for IP cleanliness scores, network type, proxy, VPN, Tor, location, and ASN. Web checks, batch jobs, and the API share the same 16-source scoring engine.

Request

FieldTypeRequiredDescription
ipstringYesPublic IPv4 or IPv6 address, up to 64 characters
curl -X POST https://iprisk.top/v1/check -H "Authorization: Bearer ipr_live_xxx" -H "Content-Type: application/json" -d '{"ip":"1.1.1.1"}'

Success response

{ "success": true, "request_id": "7f3e8d21-...", "cached": false, "credits_remaining": 9999, "billing": { "charged": true, "credits": 1, "success_sources": 16, "minimum_sources": 12, "missing_coverage_groups": [] }, "data": { "ip": "1.1.1.1", "score": 45, "cleanliness_level": "low", "ip_type": "datacenter", "proxy": false, "vpn": false, "tor": false, "hosting": true, "country": "Australia", "country_code": "AU", "city": "Sydney", "asn": "AS13335", "organization": "Cloudflare, Inc.", "success_sources": 16, "checked_at": "2026-09-20T12:00:00.000Z" } }

Response fields

FieldTypeDescription
ipstringNormalized public IPv4 / IPv6 address
scorenumber0–100 cleanliness score; higher is cleaner
cleanliness_levelstringexcellent / good / fair / low / very_low / poor
ip_typestringNetwork type, such as residential, mobile, or datacenter
proxy / vpn / torbooleanProxy, VPN, and Tor detection results
hostingbooleanWhether the address belongs to hosting or a datacenter
country / country_code / citystring | nullConsensus geolocation result
asn / organizationstring | nullAutonomous system number and network organization
success_sourcesnumberSuccessful source count, up to 16
checked_atstringISO 8601 completion timestamp
billing.chargedbooleanWhether this request was actually charged
billing.creditsnumberCredits charged for this request: always 0 or 1

During the compatibility period, risk_level remains for older clients. New integrations should use cleanliness_level.

Billing and result quality

Each request reserves one credit. It is charged only when at least 12 sources succeed and critical coverage for network identity, proxy/VPN, routing, and threat intelligence is complete. Failed or incomplete checks are automatically refunded while any usable result is still returned. Cache hits count as valid queries.

Scores and weights are identical to the web check. Raw third-party payloads are not exposed by the API.

Status codes and handling

HTTPcodeMeaningAction
400invalid_ip / unsupported_ipInvalid IP format or non-public addressFix the request; do not retry the same value
401invalid_api_keyMissing or invalid API keyCheck the Bearer key
402insufficient_creditsInsufficient creditsAdd credits or upgrade the plan
409query_in_progressThe same IP is already being checkedRetry shortly
429rate_limitedPlan rate limit exceededSlow down and back off
503engine_busy / backend_unavailableService temporarily busy or recoveringRetry with exponential backoff

Usage conventions

  • X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset describe the active window. On 429, retry after the interval in Retry-After.
  • Use HTTPS and never expose API keys in frontend code, public repositories, or logs.
  • Use request_id for troubleshooting. Share it with support, never the API key.
  • CORS is supported, but production integrations should keep and use the API key on your own server.