List Conversions

This http method allows you to list your conversions with pagination, filtering, and field selection.

List conversions

Lists your project's conversions, newest first, in pages of up to 50, over the current month and the twelve before it. Secret keys only: a public key gets 403.

gethttps://api.ip2geo.dev/conversions/list
curl --request GET \
    --url 'https://api.ip2geo.dev/conversions/list' \
    --header 'x-api-key: i2g_sk_your_secret_key'

Authorizations

x-api-keystringrequiredin: header
A secret key (i2g_sk_...). Keep it on your server: it reads every conversion your project made. A public key gets 403 here.

Query parameters

offsetintegerdefault: 0minimum: 0
How many conversions to skip, a whole number.
limitintegerdefault: 50minimum: 1maximum: 50
How many conversions to return, a whole number. Values above 50 are treated as 50.
selectstring[]
Return only these fields, comma-separated: select=data.continent.country.code,status. Repeating the parameter (select=data.asn.name&select=status) works too. Name a stored field as it is (id, uniqueId, data, status, startedAt, completedAt, createdAt) and a geolocation field by its path under data, such as data.continent.country.name (the data. prefix may be left out). uniqueId is always included, so every row can be matched to its conversion. The SELECT constants list every path.
ipSearchstring
Only conversions whose address contains this text, case-insensitive.

Responses

200A page of conversions, trimmed to select when it is given.
successbooleanrequired
Whether the request was successful.
messagestringrequired
Response message.
codeintegerrequired
HTTP status code.
dataobjectrequired
Show child attributes
conversionsobject[]required
This page of conversions, newest first.
Show child attributes
idinteger
Sequential conversion number.
uniqueIdstringformat: uuid
The conversion's id, a UUIDv7 that carries the time it was made. Always included.
dataobject
The geolocation data of one address. Every value is null when the datasets do not know it.
Show child attributes
ipstring | null
The address that was converted.
typestring | null
The address family.
Available options:ipv4ipv6null
is_euboolean | null
true when the country is in the European Union (its 27 member states, and the Åland Islands and outermost regions such as Réunion that have a country code of their own), false for any other country, null when the country is unknown.
continentobject
Show child attributes
namestring | null
codestring | null
Two-letter continent code, lowercase: af, an, as, eu, na, oc or sa.
geoname_idinteger | null
GeoNames ID for the continent.
countryobject
Show child attributes
namestring | null
codestring | null
ISO 3166-1 alpha-2 country code, lowercase.
geoname_idinteger | null
GeoNames ID for the country.
phone_codestring | null
The country's international calling code, such as +1, +44 or +7.
capitalstring | null
tldstring | null
The country-code top-level domain.
subdivisionobject
State, province, or region information.
Show child attributes
namestring | null
Name of the state/province/region.
codestring | null
ISO 3166-2 code for the subdivision, as the datasets write it (e.g., 'CA' for California).
cityobject
Show child attributes
namestring | null
geoname_idinteger | null
GeoNames ID for the city.
latitudenumber | null
longitudenumber | null
accuracy_radiusinteger | null
Radius in kilometers around the coordinates where the IP is likely located.
metro_codeinteger | null
Metro area code (US only).
postal_codestring | null
Postal code, lowercase.
timezoneobject
Show child attributes
namestring | null
IANA time zone.
time_nowstring | null
The local time in that time zone when the address was converted, written like 10/10/2026, 1:38:38 AM.
flagobject
Show child attributes
imgstring | null
A 320 px wide PNG of the flag.
emojistring | null
emoji_unicodestring | null
currencyobject
Show child attributes
namestring | null
codestring | null
ISO 4217 currency code.
symbolstring | null
registered_countryobject
The country where the IP address is registered (may differ from location country for VPNs, proxies, etc.).
Show child attributes
namestring | null
Name of the registered country.
codestring | null
ISO 3166-1 alpha-2 code of the registered country, lowercase.
geoname_idinteger | null
GeoNames ID for the registered country.
asnobject
Show child attributes
numberinteger | null
The autonomous system number.
namestring | null
The organization that announces the address.
completion_timeobject
Show child attributes
milisecondsnumber | null
How long the conversion took, in milliseconds.
secondsnumber | null
How long the conversion took, in seconds.
statusstring
success, failed (a valid address without a geolocation record, or a lookup that failed) or invalid-ip-address.
Available options:successfailedinvalid-ip-address
startedAtstringformat: date-time
When the conversion started.
completedAtstring | nullformat: date-time
When the conversion completed.
createdAtstringformat: date-time
When the conversion was created.
hasMorebooleanrequired
Whether there are more conversions after this page.
totalCountintegerrequired
How many conversions match, across every page.
_reqobjectrequired
Show child attributes
reqIdstringrequired
Unique request identifier. Quote it when you contact support.
resTimenumberrequired
Response time in milliseconds.
Example response
{
    "success": true,
    "message": "Conversions listed successfully.",
    "code": 200,
    "data": {
        "conversions": [
            {
                "id": 4825913,
                "uniqueId": "01a12452-07a0-7a3b-8c41-d2e5f6a7b8c9",
                "data": {
                    "ip": "8.8.4.4",
                    "type": "ipv4",
                    "is_eu": false,
                    "continent": {
                        "name": "North America",
                        "code": "na",
                        "geoname_id": 6255149,
                        "country": {
                            "name": "United States",
                            "code": "us",
                            "geoname_id": 6252001,
                            "phone_code": "+1",
                            "capital": "Washington D.C.",
                            "tld": ".us",
                            "subdivision": {
                                "name": "Massachusetts",
                                "code": "MA"
                            },
                            "city": {
                                "name": "Westfield",
                                "geoname_id": 4955190,
                                "latitude": 42.1293,
                                "longitude": -72.7522,
                                "accuracy_radius": 10,
                                "metro_code": 543,
                                "postal_code": "01085",
                                "timezone": {
                                    "name": "America/New_York",
                                    "time_now": "10/10/2026, 1:38:38 AM"
                                }
                            },
                            "flag": {
                                "img": "https://flagcdn.com/w320/us.png",
                                "emoji": "🇺🇸",
                                "emoji_unicode": "U+1F1FA U+1F1F8"
                            },
                            "currency": {
                                "name": "United States Dollar",
                                "code": "USD",
                                "symbol": "$"
                            }
                        }
                    },
                    "registered_country": {
                        "name": "United States",
                        "code": "us",
                        "geoname_id": 6252001
                    },
                    "asn": {
                        "number": 15169,
                        "name": "Google Llc"
                    },
                    "completion_time": {
                        "miliseconds": 3,
                        "seconds": 0.003
                    }
                },
                "status": "success",
                "startedAt": "2026-10-10T05:38:38.112Z",
                "completedAt": "2026-10-10T05:38:38.112Z",
                "createdAt": "2026-10-10T05:38:38.112Z"
            }
        ],
        "hasMore": true,
        "totalCount": 1284
    },
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}
400offset is not a whole number of 0 or more, or limit is not a whole number of 1 or more.
successbooleanrequired
Always false for an error.
messagestringrequired
What went wrong, in a sentence you can show.
codeintegerrequired
HTTP status code.
dataobject | nullrequired
Null for most errors. A 429 carries currentUsage, planLimit and plan, and a 400 for invalid conversion ids carries invalidIds.
_reqobjectrequired
Show child attributes
reqIdstringrequired
Unique request identifier. Quote it when you contact support.
resTimenumberrequired
Response time in milliseconds.
Example response
{
    "success": false,
    "message": "<string>",
    "code": 123,
    "data": null,
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}
401The x-api-key header is missing, malformed, unknown or disabled, or a public key was sent with an Origin that does not match its domain.
successbooleanrequired
Always false for an error.
messagestringrequired
What went wrong, in a sentence you can show.
codeintegerrequired
HTTP status code.
dataobject | nullrequired
Null for most errors. A 429 carries currentUsage, planLimit and plan, and a 400 for invalid conversion ids carries invalidIds.
_reqobjectrequired
Show child attributes
reqIdstringrequired
Unique request identifier. Quote it when you contact support.
resTimenumberrequired
Response time in milliseconds.
Example response
{
    "success": false,
    "message": "<string>",
    "code": 123,
    "data": null,
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}
403A public key was sent. Reading conversions takes a secret key: public keys can only convert addresses.
successbooleanrequired
Always false for an error.
messagestringrequired
What went wrong, in a sentence you can show.
codeintegerrequired
HTTP status code.
dataobject | nullrequired
Null for most errors. A 429 carries currentUsage, planLimit and plan, and a 400 for invalid conversion ids carries invalidIds.
_reqobjectrequired
Show child attributes
reqIdstringrequired
Unique request identifier. Quote it when you contact support.
resTimenumberrequired
Response time in milliseconds.
Example response
{
    "success": false,
    "message": "<string>",
    "code": 123,
    "data": null,
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}
429The project has used its plan's conversions for this period. data carries currentUsage, planLimit and plan.
successbooleanrequired
Always false for an error.
messagestringrequired
What went wrong, in a sentence you can show.
codeintegerrequired
HTTP status code.
dataobject | nullrequired
Null for most errors. A 429 carries currentUsage, planLimit and plan, and a 400 for invalid conversion ids carries invalidIds.
_reqobjectrequired
Show child attributes
reqIdstringrequired
Unique request identifier. Quote it when you contact support.
resTimenumberrequired
Response time in milliseconds.
Example response
{
    "success": false,
    "message": "<string>",
    "code": 123,
    "data": null,
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}
500Something failed on our side. Reads are safe to retry; a conversion may already have been counted.
successbooleanrequired
Always false for an error.
messagestringrequired
What went wrong, in a sentence you can show.
codeintegerrequired
HTTP status code.
dataobject | nullrequired
Null for most errors. A 429 carries currentUsage, planLimit and plan, and a 400 for invalid conversion ids carries invalidIds.
_reqobjectrequired
Show child attributes
reqIdstringrequired
Unique request identifier. Quote it when you contact support.
resTimenumberrequired
Response time in milliseconds.
Example response
{
    "success": false,
    "message": "<string>",
    "code": 123,
    "data": null,
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}
503The API is under maintenance. Retry later: https://api.ip2geo.dev/maintenance/status says when it is over.
successbooleanrequired
Always false for an error.
messagestringrequired
What went wrong, in a sentence you can show.
codeintegerrequired
HTTP status code.
dataobject | nullrequired
Null for most errors. A 429 carries currentUsage, planLimit and plan, and a 400 for invalid conversion ids carries invalidIds.
_reqobjectrequired
Show child attributes
reqIdstringrequired
Unique request identifier. Quote it when you contact support.
resTimenumberrequired
Response time in milliseconds.
Example response
{
    "success": false,
    "message": "<string>",
    "code": 123,
    "data": null,
    "_req": {
        "reqId": "01a12452-07a8-7b41-a95f-3a2c1d0e9f8a",
        "resTime": 2
    }
}
Get Started

Convert IPs into accurate location data in milliseconds.

Sign up today and get 1,000 free monthly conversions, and discover why developers trust us for fast, reliable, and affordable IP conversions.