FlowData

How do I look up up to 100 IP addresses at once?

Published on 10. November 2026

If you want to locate many IP addresses at once, for example a day's visits from your server log, you don't have to query each one separately. A batch request takes up to 100 entries in a single call.

The request

A batch lookup is a POST to https://api.flowdata.one/v1/geolocation/batch. The body is a plain JSON array with no wrapping object.

curl -X POST "https://api.flowdata.one/v1/geolocation/batch?lang=en" \
  -H "Authorization: Bearer fd_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '["8.8.8.8", "1.1.1.1", "example.com"]'

Each entry is either an IP address or domain as text, or an object with its own settings:

[
  "8.8.8.8",
  {"query": "1.1.1.1", "lang": "en"},
  {"query": "example.com", "fields": "status,country,city,query"}
]
  • query: the IP address or domain.
  • lang: the language for this entry only.
  • fields: comma-separated field names. The result for this entry then contains only those fields. Include status if you want to check whether the lookup worked.

The lang parameter in the URL sets the language for all entries that don't have their own. Without it, names come back in German. The available languages are listed in How do I look up the location of an IP address or domain?. Unlike a single lookup, an unknown language code here is not an error; the entry simply gets the default language.

The response

You get a JSON array back with one object per entry, in the same order as your entries. Each object has the same fields as a single lookup. The safest way to match results to your data is by position, because for a domain, query holds the resolved IP address rather than the domain name.

A single entry can also have "status": "fail" with a short reason in message, such as private range or invalid query. The other entries aren't affected, so check the status of each object. An entry that is neither text nor an object with query ends the same way, with invalid query and an empty query.

Domains have to be resolved first, and a batch has ten seconds in total for that. Once the time is up, the remaining domains end with invalid query, while IP addresses are still located. If you have many domains, send them in smaller batches.

Batch error messages

Before the lookup starts, FlowData checks the body. These errors have the form {"status":"fail","message":"..."}:

HTTP message Cause
400 Empty request body The body is empty.
400 Invalid JSON format The body isn't valid JSON, often because of a missing quote or comma.
400 Request body must be a JSON array The body is an object like {"ips": [...]} instead of an array.
400 At least one query required The array is empty.
422 Maximum 100 queries allowed per batch request The array has more than 100 entries.
503 Geolocation database unavailable Location lookups are unavailable right now. Try again after a short pause.

If you have more than 100 addresses, split them into batches of at most 100 and send them one after the other.

In the area's Log you can find all rejected batch requests by setting the filter to Failed. The eye icon in the row shows the exact error response. See Statistics and request log of a FlowData area for more.

What does a batch cost?

Every entry with status: success is billed. Entries with fail are free, and a rejected request costs nothing. The price per 1,000 successful lookups is the same as for a single lookup and is on the pricing page.

Before the lookup starts, FlowData sets aside the amount for all entries and afterwards charges only the successful ones. If your balance doesn't cover all entries, the API answers with HTTP 402, even if not all of them would have succeeded in the end.

Good to know

  • A batch request counts as one request in the statistics and appears as one row in the log, however many entries it contains.
  • Remove duplicate addresses before sending, so more different addresses fit into one batch.
  • As with all FlowData calls, send the request from your server so your key doesn't end up in the browser.

Was this article helpful?

Back to IP Geolocation & Client Info