---
title: "Batch IP lookup — analyze up to 100 IPs in a single request"
method: POST
path: "/api/v1/ip/batch"
tags: ["IP Geolocation & Security API"]
---

# Batch IP lookup — analyze up to 100 IPs in a single request

`POST /api/v1/ip/batch`

Performs geolocation and security analysis on multiple IP addresses in one request.

**Batch Processing**:
- Up to 100 IP addresses per request
- Duplicate IPs are automatically deduplicated
- IPs processed concurrently for sub-second total response time
- Results returned as a map keyed by IP address

**Quota Management**:
- One quota unit deducted per unique IP address
- Quota checked before any processing begins (no charge if insufficient)
- Quota deducted only after ALL lookups complete successfully
- No quota charged if batch processing fails or request is invalid

**Error Handling**:
- HTTP 400: Malformed IP address format (no charge)
- HTTP 429: Insufficient quota (no charge)
- Private/reserved IPs are included in results with limited data and still consume quota

**Use Cases**:
- Bulk fraud screening of user registrations
- Log analysis and threat intelligence
- Network auditing and security monitoring
- Geolocation of large IP datasets

## Request body

- BatchIpLookupRequestDto — JSON request containing list of IP addresses to analyze. **Request Requirements**: - Must contain 1–100 IP addresses - Each IP must be valid IPv4 or IPv6 format - Maximum 45 characters per IP address **Example Request**: ```json { "ips": [ "8.8.8.8", "1.1.1.1", "203.0.113.195" ] } ```
  - `ips` string[], required — List of IP addresses to look up. Maximum 100 IPs per request. **Format Requirements**: - Standard IPv4 dotted decimal (e.g., 8.8.8.8) - IPv6 full or compressed format (e.g., 2001:db8::1) - Maximum 45 characters per address - Must be structurally valid IP format **Batch Processing**: - Duplicate IPs are automatically deduplicated before processing - Quota is deducted only after successful completion of all lookups - Invalid IP formats result in HTTP 400 with no quota charged

## Response `200`

Batch lookup completed successfully with intelligence for all processed IPs

- BatchIpLookupResponseDto — Response object containing geolocation and security intelligence results for all processed IPs in a batch request.
  - `results` object, required — Map of IP addresses to their full intelligence results. The key is the original IP address. IPs that could not be resolved (e.g., private ranges) are excluded from the map and counted in failed_lookups.
  - `total_processed` integer, required — Total number of unique IPs processed in this batch.
  - `successful_lookups` integer, required — Number of IPs that returned a successful geolocation result.
  - `failed_lookups` integer, required — Number of IPs that could not be resolved (e.g., private ranges, reserved addresses).

## Other responses

- `400` — Bad Request — invalid IP format, empty list, or exceeds maximum batch size of 100
- `429` — Too Many Requests — insufficient quota for the batch size (no quota consumed)
- `500` — Internal Server Error — geolocation service temporarily unavailable

---

[API](https://skmtc.dev/ip-api/apis/ip-api-io-ip-geolocation-security-api.md) · [All operations](https://skmtc.dev/ip-api/apis/ip-api-io-ip-geolocation-security-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ip-api/ip-api-io-ip-geolocation-security-api/revisions/a6862f586bf3/schema)