Live DNS lookups
datapulse_live_dns answers one name synchronously; datapulse_live_dns_bulk submits up to 150 lookups and returns a receipt. Name canonicalization, hashes and bulk-receipt accounting common to every tool: datapulse_help(topic="conventions"). Registration data is datapulse_help(topic="rdap").
Resolver. Every lookup goes through a DNSSEC-validating recursive resolver with the EDNS DO flag set. It applies no content filtering, with one deliberate exception: answers that point at private, link-local or IPv6 unique-local ranges (10/8, 172.16/12, 192.168/16, 169.254/16, fd00::/8, fe80::/10) are dropped, so a name such as 10.0.0.1.nip.io returns NOERROR with no answer and datapulse_domain_overview reports resolves: false. The same ranges are dropped when wrapped in an IPv6 form that carries an IPv4 address: IPv4-mapped (::ffff:10.0.0.1), the deprecated IPv4-compatible form (::10.0.0.1) and 6to4 (2002:a00:1::). Every NAT64 address (64:ff9b::/96, 64:ff9b:1::/48) is dropped, private inside or not. Loopback is kept in every form (127.0.0.1, ::1, ::ffff:127.0.0.1): domains sinkholed to it are worth seeing. The scraper’s own connection guard is separate and stricter: it refuses all of these, loopback included. The resolver is not exposed or configurable. DNS answers are never served from an application cache, so force is rarely needed.
datapulse_live_dns
| Parameter | Type | Required | Description |
|---|---|---|---|
domain | string | One of domain / dns_query_hash | Name to query (IDN accepted). Its spelling is canonicalized and no labels are removed: www.example.com and example.com resolve independently. A single label (com) and underscore names (_dmarc.example.com) are fair DNS questions and accepted. Give this or dns_query_hash |
dns_query_hash | string | One of domain / dns_query_hash | The stored row for this hash, read instead of a new lookup: the submitted[].dns_query_hash of a datapulse_live_dns_bulk receipt. The row keeps the record type it was looked up with, so record_type and force do not apply; full does. The API writes a DNS row only when the lookup has run (normally seconds after a bulk receipt), so a lookup still queued, a refused item and an unknown hash all answer found: false, with a note |
record_type | string | No | One type: A, AAAA, CNAME, MX, NS, TXT, SOA, PTR, SRV, CAA, DNSKEY, DS, RRSIG, NSEC, TLSA, NAPTR, SSHFP |
force | boolean | No | Fresh lookup (default false) |
full | boolean | No | Raw resolver output instead of the summary (default false) |
Default lookup. Without record_type the tool queries A, AAAA, MX, NS, TXT, SOA, CNAME, CAA, DNSKEY and DS, plus a _dmarc.<domain> TXT lookup, in one call. With record_type it queries that one type for the exact name given and skips the DMARC lookup: the way to ask for SRV (_sip._tcp.example.com), PTR (14.5.217.172.in-addr.arpa), TLSA, NAPTR or SSHFP.
Summary response
{
"status": "ok",
"dnssec_signed": true,
"records": {
"A": [{"name": "example.com", "ttl": 3600, "data": {"address": "93.184.216.34"}}],
"MX": [{"name": "example.com", "ttl": 3600, "data": {"preference": 10, "exchange": "mail.example.com"}}]
},
"dmarc": {"status": "found", "record": "v=DMARC1; p=reject; rua=mailto:dmarc@example.com"},
"query_time_ms": 42,
"dns_query_hash": "a379a6f6...",
"domain_hash": "a379a6f6..."
}
status | records | Meaning |
|---|---|---|
ok | Records grouped by type; {} when the name has none of the types asked for | The name exists (NOERROR). A lookup that answered NOERROR with no record and no SOA adds a note: that is how the resolver answers when it withholds private, link-local or unique-local addresses, so the name may point only at such addresses |
nxdomain | The SOA from the authority section, when available | The name does not exist |
servfail | Empty | Server failure: often a DNSSEC validation failure, possibly an upstream problem. A DNSKEY/DS query with full=true shows the trust chain |
error | Empty | The lookup itself failed; error holds the worker’s text verbatim |
records: an object in every answer ({}when empty), answer records grouped by type, duplicates removed, names case-folded without a trailing dot. DNSSEC record types (RRSIG, NSEC, NSEC3, NSEC3PARAM, DNSKEY, DS) are left out unless one of them is the requestedrecord_type. Withrecord_type,recordsholds that type plus any CNAME records the resolver followed: an alias answers every question with its CNAME chain, so an alias whose target has no record of the type asked for showsCNAMEalone (www.github.comwithrecord_type=AAAAgives one CNAME togithub.comand no AAAA), not an empty object. A PTR target is underptr({"ptr": "dns.google"});full=truekeeps the resolver tool’s own key,cname.dmarc(default lookup only):statusfoundwithrecord,none(the lookup answered and there is nov=DMARC1record, NXDOMAIN included) orunknown(the DMARC lookup itself failed, SERVFAIL or REFUSED, so whether a record exists was not determined). Querying a_dmarc.name directly answers for that name; the DMARC block is then the lookup of_dmarc._dmarc.<domain>. The lookup covers the exact name only: a subdomain with no record of its own is governed by its registrable domain’ssp=(elsep=), sononethere is not “unprotected” (datapulse_help(topic="email_security")).dns_query_hashis the key the row is stored under: the A-label name withwww.kept, plus the record type when one was requested. It does not join with other tools.domain_hashis the canonical www-stripped hash shared withdatapulse_domain_overview,datapulse_live_domain_healthand the scrape tools.
Full response
full=true returns the stored lookup record instead of the summary: id, domain, record_type, status (the job’s status, completed, not the ok/nxdomain of the summary), created_at, completed_at, query_time_ms, total_time_ms, dns_query_hash, domain_hash, and raw_output.responses, the raw resolver output: per-query flags (qr, opcode, aa, tc, rd, ra, ad, cd, rcode), answers with their RRSIGs, authorities and additionals. The rcode gives finer distinctions, such as NOERROR with no answers (NODATA). For a successful lookup authorities is normally empty, because a recursive resolver follows referrals itself; it is populated on negative answers. additionals carries glue when the nameservers are in-bailiwick.
DNSSEC
dnssec_signed is true when the AD (Authenticated Data) flag was set in any response for the name, and always false for servfail and error.
| Case | dnssec_signed | Meaning |
|---|---|---|
| Unsigned zone (e.g. google.com) | false | Nothing to validate |
| Signed zone, validated | true | Data authenticated |
| Signed zone, not validated | false | Validation did not succeed for this answer |
| NXDOMAIN, denial authenticated (a missing name in a zone signed without opt-out) | true | The name provably does not exist |
NXDOMAIN, denial rests on NSEC3 opt-out (any missing .com / .net name) | false | Expected, not a validation failure (below) |
To inspect the chain, query DNSKEY and DS with record_type: the summary keeps the type asked for, and full=true adds their RRSIGs and flags.
datapulse_live_dns(domain="example.com", record_type="DNSKEY")
datapulse_live_dns(domain="example.com", record_type="DS", full=true)
Negative answers. On NXDOMAIN, dnssec_signed says whether the denial of existence was authenticated, not whether the parent zone is signed. A zone signed with NSEC3 opt-out (.com and .net are) cannot prove that a name is absent, because an opt-out span may hide unsigned delegations, so RFC 5155 §9.2 forbids a validator to set AD on such a denial. Every nonexistent .com name therefore returns nxdomain with dnssec_signed: false, from this resolver and from Cloudflare, Google and Quad9 alike; it does not mean the answer was forged. In full=true output the opt-out is visible on the NSEC3 records in authorities: their data is the raw RDATA as bytes (hash algorithm, flags, iteration count, salt length and salt, hash length and next hashed owner, type bitmap), and flags bit 1 set marks opt-out. The nxdomain status, not dnssec_signed, is what says the name does not exist.
RRSIG key_tag is not unique. Managed DNS providers (Cloudflare, for one) reuse key material across customer zones, so unrelated domains can share a key_tag. A shared value points at a shared provider, not a shared key or owner.
datapulse_live_dns_bulk
Up to 150 lookups per request, each {"domain": ..., "record_type"?, "force"?}; any other item field is refused, naming the item, before anything is sent. The tool returns a receipt, not records. Each result is read back with datapulse_live_dns(dns_query_hash=...) using the item’s submitted[].dns_query_hash, which reads the stored row; datapulse_live_dns(domain=...) does a fresh lookup of its own and never reads the bulk row. Bulk lookups share one queue with single lookups.
Seven inputs — example.com, WWW.Example.COM. (A), 💩.la, exa mple.com, a blank, Example.com. and foo.localhost — produce:
{
"accepted": 2, "rejected": 1, "cached": 0,
"errors": ["invalid_input"],
"rejected_items": [{"index": 2, "query": "xn--ls8h.la", "error": "invalid_input"}],
"rejected_local": [
{"index": 3, "query": "exa mple.com", "error": "invalid domain \"exa mple.com\": invalid domain format: ..."},
{"index": 4, "query": "", "error": "invalid domain \"\": domain cannot be empty"},
{"index": 6, "query": "foo.localhost", "error": "invalid domain \"foo.localhost\": localhost and names under it are reserved for the local host (RFC 6761) and are never looked up"}
],
"duplicates": [{"index": 5, "query": "Example.com.", "first_index": 0}],
"submitted": [
{"index": 0, "query": "example.com", "domain_hash": "a379a6f6...", "dns_query_hash": "a379a6f6...", "job_id": "7d6135b1-..."},
{"index": 1, "query": "www.example.com", "record_type": "A", "domain_hash": "a379a6f6...", "dns_query_hash": "59809847...", "job_id": "f25bfe16-..."},
{"index": 2, "query": "xn--ls8h.la", "domain_hash": "b31f96fc...", "dns_query_hash": "b31f96fc..."}
]
}
submittedlists every item sent, in canonical form, withdns_query_hash(the key to read it back),domain_hash, andjob_id/cachedwhen the API’s per-item report carries them. Sent is not accepted:💩.lawas sent and the API refused it, so it has nojob_idand no row, and appears inrejected_items.rejected_itemsis what the API refused, with its code;errorsholds those codes only, and is[]whenever nothing reached the API to be refused.rejected_localis what was refused before the request (not a valid name, blank, orlocalhostand names under it, which RFC 6761 reserves). These are not counted inrejected.duplicatescanonicalize to an earlier item with the same record type and are submitted once.cachedis always 0: DNS is never answered from an application cache.accepted + cached + rejected + len(rejected_local) + len(duplicates)equals the number of items passed (2 + 0 + 1 + 3 + 1 = 7 above).- When no item can be sent, nothing is sent: the call is an error whose text is this receipt, with every item in
rejected_local, the counts 0, the other lists[], and anote.
Generated from the live server (DataPulse MCP v0.9-341-g27163c2) on October 20, 2026. Your AI assistant reads this page by calling datapulse_help(topic="dns").