MCP documentation menu

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

ParameterTypeRequiredDescription
domainstringOne of domain / dns_query_hashName 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_hashstringOne of domain / dns_query_hashThe 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_typestringNoOne type: A, AAAA, CNAME, MX, NS, TXT, SOA, PTR, SRV, CAA, DNSKEY, DS, RRSIG, NSEC, TLSA, NAPTR, SSHFP
forcebooleanNoFresh lookup (default false)
fullbooleanNoRaw 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..."
}
statusrecordsMeaning
okRecords grouped by type; {} when the name has none of the types asked forThe 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
nxdomainThe SOA from the authority section, when availableThe name does not exist
servfailEmptyServer failure: often a DNSSEC validation failure, possibly an upstream problem. A DNSKEY/DS query with full=true shows the trust chain
errorEmptyThe 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 requested record_type. With record_type, records holds 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 shows CNAME alone (www.github.com with record_type=AAAA gives one CNAME to github.com and no AAAA), not an empty object. A PTR target is under ptr ({"ptr": "dns.google"}); full=true keeps the resolver tool’s own key, cname.
  • dmarc (default lookup only): status found with record, none (the lookup answered and there is no v=DMARC1 record, NXDOMAIN included) or unknown (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’s sp= (else p=), so none there is not “unprotected” (datapulse_help(topic="email_security")).
  • dns_query_hash is the key the row is stored under: the A-label name with www. kept, plus the record type when one was requested. It does not join with other tools. domain_hash is the canonical www-stripped hash shared with datapulse_domain_overview, datapulse_live_domain_health and 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.

Casednssec_signedMeaning
Unsigned zone (e.g. google.com)falseNothing to validate
Signed zone, validatedtrueData authenticated
Signed zone, not validatedfalseValidation did not succeed for this answer
NXDOMAIN, denial authenticated (a missing name in a zone signed without opt-out)trueThe name provably does not exist
NXDOMAIN, denial rests on NSEC3 opt-out (any missing .com / .net name)falseExpected, 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..."}
  ]
}
  • submitted lists every item sent, in canonical form, with dns_query_hash (the key to read it back), domain_hash, and job_id/cached when the API’s per-item report carries them. Sent is not accepted: 💩.la was sent and the API refused it, so it has no job_id and no row, and appears in rejected_items.
  • rejected_items is what the API refused, with its code; errors holds those codes only, and is [] whenever nothing reached the API to be refused.
  • rejected_local is what was refused before the request (not a valid name, blank, or localhost and names under it, which RFC 6761 reserves). These are not counted in rejected.
  • duplicates canonicalize to an earlier item with the same record type and are submitted once.
  • cached is 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 a note.

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").