Read a response
What null, empty lists, stale states and the dates in a response mean, and what they don't.
Every response separates what we observed from what we don't know. These rules hold across the API.
Null means unknown, never false
is_datacenter is true only when the IP sits inside a range a cloud or hosting provider publishes, and is_cdn
only inside a range a CDN publishes (an edge server, not the customer's origin). Outside every range we have, they are
null, which does not mean the IP isn't hosted: many hosting
companies publish no range list. The same goes for every other field that can be null: we don't know, so we don't
say.
Empty means not observed here, not absent
An IP with no domains means none of the domains we resolve were seen on it, not that no website is hosted there. A
domain we don't resolve answers observed: false from domain_history: say it isn't
covered, not that it has no DNS. See Data and coverage for what we resolve.
The dates
All times are UTC, in ISO 8601.
| Field | Meaning |
|---|---|
first_observed | When we first saw this answer. The record may be older; this is when we saw it. |
last_confirmed | When we last saw the same answer. |
ended_at | When we saw that the answer had changed. The change happened between last_confirmed and ended_at, not at either instant. null while it is still current. |
current | true while the answer is part of the domain's latest state. |
DNS outcomes
A domain's current state (in domain_history) says how the last query went:
outcome_class | outcome | Meaning |
|---|---|---|
positive | positive | It answered with addresses. |
negative | nxdomain, nodata | The name doesn't exist, or has no record of this type. |
transient | timeout, servfail, malformed | The query failed. The earlier answer is kept. |
A failure never erases an answer, and a change in TTL or answer order is not a change of address.
Staleness
A current state carries last_confirmed, age_seconds and stale. It is stale: true, with a stale_reason, when:
transient_failure: the last query failed, so the answer shown is the last good one;never_confirmed: no query for it has succeeded yet;older_than_seven_days: it was last confirmed more than seven days ago.
Check stale and age_seconds before you rely on a current answer.
Networks
asncomes from the IPtoASN mapping, not from our own view of BGP. The network that routes an IP is not necessarily the holder of the address or the company using it.asn.category(isp,hosting,cdn,business,banking,education_research,government_admin) is what the routing network mainly is, by our own classification where we have one (category_source: "own") and ipverse's where we don't ("ipverse"). It describes the network, not the IP's tenant, and it can be wrong. It never setsis_datacenter.asn.network_role(tier1_transit,major_transit,midsize_transit,access_provider,content_network,stub) is the network's place in routing, from ipverse as-metadata.- A CDN edge is not the customer's origin server, and domains that share an IP don't share an owner.
Usage ranges
provider_ranges can also hold ranges that say how an IP is used, each from the operator's own published list:
tor_exit (Tor exits), relay (iCloud Private Relay egress) and crawler (Google and DuckDuckGo crawlers). They
never name who hosts the IP. An IP on none of these lists is simply not listed; that is not a "no".
What every response carries
| Field | What it is |
|---|---|
coverage | What the response is based on: the observation window, the seed list and derived names, the resolver, PTR counts, and semantics, these reading rules in short. |
attribution | The sources to credit if you republish the data. |
release | The data snapshot that answered: its id and built_at. |