API reference/The lookup report

The lookup report

Field by field reference for the lookup response.

Every lookup endpoint returns this object. Fields the sources could not answer are null (rendered as n/a on the website); clients should ignore fields they do not recognise, because additive fields may appear within v1.

Top level

Field	Type	Meaning
`query`	object	The interpreted query.
`ip`	object or null	Address facts, for address lookups.
`registration`	object or null	The registry record.
`routing`	object or null	Current routing state.
`asn`	object or null	Profile of the origin AS.
`originHistory`	array	Every AS that ever originated the space.
`intel`	object	Per address intelligence sampling.
`timeline`	array	Every dated event, sorted.
`insights`	array	Plain language findings.
`tags`	object	Confirmed and suggested labels.
`sources`	array	Provenance per dataset.
`meta`	object	Timing, cache and truncation information.

query and ip

Field	Type	Meaning
`query.raw`	string	Exactly what was asked.
`query.kind`	string	`ip`, `prefix` or `asn`.
`query.normalized`	string	The canonical form the report is about, for example `AS13335`.
`ip.address`	string	The normalised address.
`ip.family`	string	`ipv4` or `ipv6`.
`ip.specialUse`	object or null	Set for reserved space: `label`, `note` and the reserving `cidr`.

registration

Field	Type	Meaning
`rir`	string or null	The responsible registry.
`cidr`	string or null	The registered block containing the queried address. Null when the allocation is not one CIDR; the range fields then carry the answer.
`cidrs`	array	Every CIDR the allocation covers, in the registry's order.
`startAddress`, `endAddress`	string or null	The allocation's range.
`addressCount`	string or null	Number of addresses in the range, as a string because a large IPv6 block overflows a number.
`handle`, `name`	string or null	The registry's identifiers.
`type`	string or null	The registry's classification, verbatim.
`status`	array	Registry status flags, verbatim.
`country`	string or null	Registered country.
`orgName`	string or null	Holding organisation.
`registeredAt`, `lastChangedAt`, `allocatedAt`	string or null	Registry dates.
`abuseEmail`	string or null	Published abuse contact.
`parties`	array	Contacts, each with `role`, `name`, `org`, `handle`, `email`, `phone`, `address`.
`parents`	array	Parent blocks, each with `cidr`, `name`, `handle`, `type`, `country`.
`remarks`	array	Registry remarks, verbatim.
`whois`	array	Raw key and value pairs for the raw view.

routing

Field	Type	Meaning
`announced`	boolean or null	Whether the covering prefix is visible in global BGP. Null when no routing source answered.
`prefix`	string or null	The announced covering prefix.
`origins`	array	Originating ASes, each `{ asn, holder }`.
`rpki`	object or null	`status` plus `roas`, each `{ origin, prefix, maxLength, validity }`.
`moreSpecifics`	number or null	Announcements inside the covering prefix.
`lessSpecific`	string or null	The covering announcement above, when one exists.

asn

Field	Type	Meaning
`asn`	number	The AS number.
`name`, `description`, `orgName`	string or null	Identity as published.
`country`, `rir`	string or null	Registration location and registry.
`allocatedAt`, `registeredAt`, `lastChangedAt`	string or null	Registry dates.
`allocationStatus`	string or null	Registry allocation status.
`website`	string or null	Published website.
`abuseEmails`, `contactEmails`	array	Published contact addresses.
`ownerAddress`	array	Registered postal address lines.
`announced`	boolean or null	Whether the AS currently announces anything.
`prefixCountV4`, `prefixCountV6`	number or null	Announced prefix counts by family.
`prefixes`	array	Preview of announced blocks: `prefix`, `family`, `firstSeen`, `lastSeen`, `ongoing`.
`prefixTotal`	number	True total behind the preview.
`upstreams`, `downstreams`	array	Neighbour previews: `asn`, `name`, `country`, `strength`.
`neighbourCounts`	object or null	True totals: `upstreams`, `downstreams`, `uncertain`.
`ixs`	array	Exchange presence: `name`, `country`, `city`, `speed`.
`ixDataAvailable`	boolean	False when the exchange dataset was not queried. An empty `ixs` proves nothing then.
`peeringdb`	object or null	Self declared profile: `registered`, `id`, `name`, `infoType`, `traffic`, `scope`, `ratio`, `policy`, `website`, `irrAsSet`, `created`, `updated`.
`parties`	array	Contacts, same shape as registration parties.
`space`	object or null	Sampling across announced space, below.

asn.space

Field	Type	Meaning
`blocks`	array	One entry per shown block, below.
`shown`	number	Blocks shown, which may be fewer than announced.
`announced`	number	Blocks the AS announces.
`sampled`	number	Sampled blocks shown.
`sampledTotal`	number	Sampled blocks that exist, before the display cap.
`clean`, `mild`, `flagged`, `unsampled`	number	Block counts by status.

Each entry of blocks:

Field	Type	Meaning
`prefix`	string	The announced block.
`sampled`	number	Addresses checked inside it.
`anonymity`, `infrastructure`, `clean`	number	Sampled addresses by category.
`status`	string	`flagged`, `mild`, `clean` or `unsampled`.
`maxRisk`	number or null	Worst risk score seen inside.
`example`	string or null	An address to open for the story.
`note`	string	One line summary.

originHistory

One row per AS that has ever originated the space:

Field	Type	Meaning
`asn`, `holder`	number, string or null	The origin network.
`prefix`	string	The exact prefix it announced.
`scope`	string	How that prefix relates to the queried space.
`firstSeen`, `lastSeen`	string, string or null	The observed window.
`ongoing`	boolean	Whether the announcement is current.
`windowCount`	number	Distinct visibility windows.
`peakPeers`	number or null	Most full BGP peers that saw it.

intel

Field	Type	Meaning
`enabled`	boolean	False when no per address feed is configured.
`sampledFrom`	string or null	The block addresses were sampled from. Null for a single address query.
`samples`	array	One row per feed per address, below.
`rollup`	object	Block level summary, below.
`changes`	array	Verdict flips: `ip`, `provider`, `at`, `field`, `before`, `after`.
`trend`	object	Risk over time per feed, with `daysObserved` and `observations` stating how much data stands behind it.
`addresses`	array	One per sampled address, below.
`groups`	array	Addresses collapsed by behaviour: `category`, `label`, `note`, `count`, `example`.
`flaggedShare`	array	Twelve months of `{ month, label, pct, sampled, risk }`. `pct` is null for a month nobody looked; that is not zero.
`blockSize`	string or null	Addresses in the queried block, as a string because a /8 overflows a number.
`samplesTruncated`	boolean	True when the read hit its row cap, so every count in `rollup` is a floor rather than a total. The cap counts rows and one address rated by three feeds spends three of them, so a large swept block can reach it. Check this before treating `addressesChecked` as the whole picture.
`activeScanBlock`	object or null	Result of our own active check on the covering block: `proxies` (count of addresses confirmed answering as proxies) and `scannedAt` (ISO 8601). Null when the block has not been actively checked.
`activeScanCoverage`	object or null	On an ASN report, what our own scanning covered: `blocksChecked`, `blocksWithExits`, `announcedBlocks` (merged /24-equivalents, or null when we have not enumerated it), `announcedAsOf`, `announcedSource`, `provenShare`, `labelled`, `asOf`. Present whether or not the network carries a label, so findings are visible either way. `provenShare` is null whenever `announcedBlocks` is null or the measured count exceeds it, and is never above 1. Null for a non-ASN subject or a network we have not scanned.

intel.samples

Each row is one feed's reading of one address: ip, provider, firstSeen, lastSeen, observations, the verdicts isVpn, isProxy, isTor, isDatacenter, isAbuser, isMobile, isBlacklisted (each true, false or null), riskScore and riskLabel, ispRiskScore and ispRiskLabel, blocklistCount and blocklists, plus context: asn, asnOrg, asnType, company, companyType, org, country, service, serviceType.

intel.rollup

Field	Type	Meaning
`addressesChecked`	number	Distinct addresses sampled.
`vpn`, `proxy`, `tor`, `datacenter`, `abuser`, `blacklisted`	number	Addresses carrying each verdict.
`maxRiskScore`	number or null	Worst risk score seen.
`addressesAtMaxRisk`	number	Distinct addresses at that worst score.
`avgRiskScore`	number or null	Average across sampled addresses.
`maxIspRiskScore`, `ispRiskLabel`	number or null, string or null	Worst operator level risk any feed assigns.
`maxBlocklistCount`	number or null	Most public blocklists carrying any one address. Null means no feed had a blocklist verdict at all, which is not zero.
`blocklists`	array	Every list that flagged anything here, unioned. A different quantity from the count above.
`services`	array	Services detected on sampled addresses.
`asns`, `orgs`	array	Operating networks and organisations seen.
`tenants`	array	Organisations using the space where they differ from the ISP.
`agreement`	object	Per verdict: `{ agree, sole, contested, feedsTrue, feedsRated }`. How much of each count rests on one unopposed feed.
`mixed`	boolean	True when sampled addresses disagree about what the block is.

intel.addresses

Field	Type	Meaning
`ip`	string	The address.
`category`	string	`anonymity`, `infrastructure`, `lapsed` or `clean`.
`risk`, `riskLabel`	number or null, string or null	Highest score any source reported for this address, with that source's own label.
`riskFrom`	string or null	Which source supplied `risk`, because the sources do not measure the same quantity. `scamalytics` is a fraud rate over web sessions, which that vendor scopes to web traffic rather than server to server connections, and which falls back to the operator average for an address they have not observed; a low value there can mean few observations rather than a clean address. `activescan` is our own connection to the address. Null exactly when `risk` is null.
`disagree`	boolean	Feeds place the address in different bands of the scale (low, medium, high), so one number would mislead. Differing numbers within a band do not set this.
`confirmed`	boolean	Our own check found this address serving as a proxy, and it still is. A separate claim from `risk`: that is what feeds think of the network, this is what we measured at the address.
`lastConfirmedAt`	string or null	When we last saw it serving, whether or not it still is. `confirmed` false with a date here means a proxy that has gone quiet, and `category` is then `lapsed`. Null means we have never caught it serving, which is not the same as clean: it may never have been checked.
`checks`	number	Total readings of this address.
`lastSeen`	string or null	Last reading.
`chips`	array	Short verdict labels for display.
`contested`	array	The subset of `chips` one feed asserts and another denies. Hedge these.
`note`	string	One line summary.
`spark`	array	Risk on each day observed, oldest first.

timeline and insights

Timeline events are documented under History and archive: at, until, ongoing, category, title, detail, source, data.

Field	Type	Meaning
`insights[].level`	string	`info`, `notice` or `warn`.
`insights[].code`	string	Stable machine readable identifier for the finding.
`insights[].lead`	string	The short claim.
`insights[].text`	string	The explanation that earns it.

Field	Type	Meaning
`asn`	array	Confirmed tags on the origin AS.
`prefix`	array	Confirmed tags on blocks covering or overlapping the subject.
`suggested`	array	Machine proposals awaiting an analyst: `tagSlug`, `label`, `category`, `severity`, `color`, `confidence`, `rationale`, `source`.
`maxSeverity`	number	Highest severity across confirmed tags. Drives the banner.

sources

Field	Type	Meaning
`provider`	string	Source id, matching `/api/v1/sources`.
`dataset`	string	Which of the source's datasets this row is about.
`ok`	boolean	Whether it answered usefully.
`state`	string	`fresh`, `revalidating`, `refreshed`, `stale`, `pending` or `error`. See Data freshness and caching.
`status`	number	Upstream HTTP status.
`ageMs`	number or null	Age of the cached answer.
`fetchedAt`	string or null	When it was fetched.
`error`	string or null	What went wrong, when something did.

Field	Type	Meaning
`generatedAt`	string	When the report was assembled.
`durationMs`	number	Assembly time.
`cacheHit`	boolean	At least one dataset came from cache.
`fullyCached`	boolean	Every dataset came from cache.
`partial`	boolean	A dataset was still pending or failed. True whenever `pendingDatasets` or `failedDatasets` is above zero.
`pendingDatasets`	number	Datasets still being fetched when the report was sent.
`failedDatasets`	number	Datasets whose source failed with nothing cached to fall back on.
`retryAfterMs`	number or null	How long to wait before repeating the lookup, in milliseconds. Null when the report is complete. See Data freshness and caching.
`omittedAnnouncements`	number	Routing announcements left off the timeline for size.