Bulk lookup

Use bulk lookup when you need to process large IP lists with server-side pagination.

Endpoint: POST /api/v1/lookup/bulk
Plan: Professional and Enterprise (see Billing)

Query parameters

Name	Default	Description
`page`	`1`	Page number (≥ 1)
`page_size`	`50`	Results per page (1–1000)

Request body

{
  "ips": ["8.8.8.8", "1.1.1.1", "9.9.9.9"]
}

Field	Required	Description
`ips`	yes	Array of IPv4 or IPv6 strings

Example

curl -s -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  "https://YOUR_PLATFORM_HOST/api/v1/lookup/bulk?page=1&page_size=50" \
  -d '{"ips": ["8.8.8.8", "1.1.1.1"]}'

Response

{
  "data": [
    { "ip": "8.8.8.8", "location": { "country_code": "US" }, "asn": { "number": "15169", "name": "GOOGLE" } },
    { "ip": "1.1.1.1", "location": { "country_code": "AU" }, "asn": { "number": "13335", "name": "CLOUDFLARENET" } }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total": 2,
    "total_pages": 1
  }
}

When page is beyond available data, data is an empty array and pagination still reflects totals.

Errors

Status	Code	When
`400`	`INVALID_REQUEST`	Malformed JSON or missing `ips`
`400`	`MISSING_IPS`	Empty `ips` array
`500`	`BULK_LOOKUP_FAILED`	Lookup processing error

Individual IPs that fail inside a page may include an error field on the object instead of failing the entire HTTP request.

Limits

Maximum request body size: 10 MB
page_size range: 1–1000
Each IP in the list counts toward your monthly lookup quota