MCP documentation menu

Domain health probe

datapulse_live_domain_health runs a live technical health check of one domain and returns the full report. It is always synchronous and always live: every call queues a new probe and returns that probe’s report (a stored report is never served in its place), and created_at is the time of the probe you asked for, so a portfolio audit can verify freshness from the record itself.

Every key of the report, the not-determined conventions, the enumerations and the code-to-severity table are in datapulse_help(topic="domain_health_fields"). This topic covers what the probe checks, its inputs and timing, and how to read the verdict.

What is checked

  • DNS, DNSSEC-validated: A, AAAA, MX, TXT and NS at the apex; A and AAAA for www. Addresses in reserved ranges (RFC 1918, loopback, link-local, CGNAT, documentation, multicast, ULA) are reported under reserved_addresses and not probed.
  • DNSSEC state of the zone (secure, insecure, island, bogus, servfail, unknown, nonexistent), with DS and DNSKEY presence.
  • Delegation: a trace from the root servers compares the NS set the parent delegates with the NS set the zone serves, bypassing the recursive resolver.
  • Nameserver audit (zone apexes only): every nameserver address asked for the SOA over UDP, TCP and EDNS; serial agreement, /24 and /48 diversity, glue. No zone transfer is requested.
  • Web: TCP 80 and 443 on every apex and www address; the TLS chain and certificate on 443, with TLS 1.0/1.1 acceptance; one GET / per port per address with HSTS; HTTP/1.1, HTTP/2 and HTTP/3 (QUIC) support; the HSTS preload status from a cached copy of the Chromium list. Port 25 is never probed.
  • Redirects are not followed (redirect_log: false). Each address’s http and https entry is one response with its status and Location. The full chain a browser follows is the scrape’s redirect_chain, on datapulse_scrape_result and datapulse_domain_overview.
  • Mail (zone apexes only): DMARC, SPF evaluated with includes and redirects followed and lookups counted, MX target sanity, DKIM at a fixed list of selectors (dkim.selectors_probed), MTA-STS and TLS-RPT. No SMTP connection is made. Mail posture as a whole is covered in datapulse_help(topic="email_security").
  • Certificate policy: CAA per host against the issuer that host served; DANE/TLSA against every served chain.
  • Wildcards: random labels looked up to see whether the zone answers names nobody published.

Input

One parameter, domain. Its spelling is canonicalized as described in datapulse_help(topic="conventions"), and no labels are removed: the probe itself checks both the apex and www. Beyond that, three rules are specific to this tool:

  • The top-level label is never all digits (3.14 and 1.1.1.1 are refused, RFC 3696) and never contains an underscore (foo._com).
  • The registrable domain contains no underscore (exa_mple.com is refused: DNS allows _ in an owner name, but no registry registers one). Service labels elsewhere are fine: _dmarc.example.com and _443._tcp.example.com are valid inputs.
  • A leading digit is fine: 1password.com and 7-eleven.com are accepted.

IP literals and single labels (localhost) are refused before any request is made.

Timing

LimitValueMeaning
Probe budget3 s per DNS lookup set, 2 s per TCP connect, TLS handshake or HTTP request, 2 s per QUIC handshakeIn the report as timeout_sec, tcp_timeout_sec, quic_timeout_sec. A healthy domain typically finishes in under 4 s (0.4–3.8 s for eight well-known domains, measured 2026-10-20). A whole-run deadline (max_time_sec, 18 s) caps it, so a report is always written; a run cut off there carries deadline_reached: true, and the checks still running report their own timeouts, which read as not determined.
Worker kill20 sA probe that has not finished is stopped and stored with status: "failed".
Tool wait30 sHow long this tool holds the request open. A probe still running then is answered with its receipt only, {status, job_id, domain_hash} and no report; it finishes server-side, and a fresh call runs a new probe.

Response

The response is the lookup record; raw_output is the probe report, verbatim.

FieldMeaning
idJob id of the probe this call queued
domainThe probed domain as the API reports it
domain_hashThe domain hash (see datapulse_help(topic="conventions")); joins with datapulse_domain_overview and datapulse_live_dns
statuscompleted when the probe ran, healthy or not; failed when the probe itself could not run
raw_outputThe report; absent when status is failed
errorWhy the probe could not run; only when status is failed
created_at, completed_atWhen the probe was queued and when it finished
query_time_ms, total_time_msProbe duration and end-to-end duration on the worker
submitted_domainWhat was sent, when canonicalizing a non-ASCII name changed which domain is asked about. A fullwidth homograph such as example.com folds to example.com, so the report describes the legitimate domain, and this field is the only record that a different name was submitted

A multi-address domain produces a report of roughly 5–15 KB. The latest report for a domain is kept for about 24 hours; each new probe replaces it.

Reading the verdict

status is "completed" even when the domain is broken. The verdict is inside the report:

  • raw_output.ok is true when raw_output.errors is empty.
  • raw_output.findings lists every result as {code, severity, host, message}. code is stable and is the field to match on; message wording can change. severity is fail, warn or info, and a code always has the same severity: fail entries are exactly errors, warn entries are exactly warnings, in the same order, and info entries appear only in findings. Severity comes from findings, not from which array a sentence sits in.
  • warn is a defect worth fixing. info is a configuration fact that many well-run domains share and that says nothing on its own, such as no AAAA, a null MX, DMARC p=none, TLS 1.0/1.1 kept for legacy clients, or nameservers in one IPv6 /48 (anycast). A flagship such as wikipedia.org carries only info. The full code table is in datapulse_help(topic="domain_health_fields").
  • A dead zone is one finding. When the parent delegates the zone but no delegated nameserver answers for it, errors holds exactly one entry (code zone_unreachable) naming each nameserver and what it did, and nothing else is reported, since no other check could work. If even one nameserver answers, the full report is produced.
  • A domain whose HTTPS is entirely unreachable is still ok: true, with one warning per address; filter on the web section or the warnings, not only on ok.

status is "failed" (with error and no raw_output) only when the probe tool itself could not run: a usage error, a missing helper, or the 20-second worker kill. It says nothing about the domain.

Names that do not exist

NXDOMAIN is not the test for whether a name exists. A signed zone using compact denial of existence (Cloudflare’s, for example) answers NOERROR with no records for a missing name. The report judges the meaning instead: when every apex lookup answered and none returned a record of any type, it fails with apex <name> has no records of any type (code apex_empty), as it does for NXDOMAIN. A name someone created has at least one record of some type; a mail-only host still has an MX. Requiring every lookup to have answered keeps a failed probe from being read as an empty name. A typo therefore returns ok: false whichever provider hosts the zone, as one error.

A name that does not exist also has no mail, caa or tlsa section and no not_delegated finding beside apex_nxdomain: there is no zone to configure, so a missing DMARC record or CAA policy is not a finding.

Names outside the global DNS

A name under invalid, test, localhost, example (RFC 6761), local (RFC 6762), onion (RFC 7686) or home.arpa (RFC 8375) never resolves by definition. A validating resolver answers it locally with an unsigned denial, which read naively looks like a broken trust chain. The report carries reserved_name with the RFC, dnssec.state reads unknown rather than bogus, the delegation, nameserver and mail checks are skipped, and one warning (reserved_name) says why. example.com and its siblings are reserved for documentation but are really delegated, so they are checked like any other domain.

Names inside a zone

A host rather than a zone apex is reported with not_a_zone: true, delegation.status: "not_a_zone", enclosing_zone when a SOA revealed it, and no mail, nameservers or web.www; the delegation and zone DNSSEC checks are skipped. Two shapes land here: a name whose NS query returned no records (mail.google.com, _dmarc.example.com), and a CNAME (gist.github.com to github.com), which RFC 1034 rules out as an apex.

For a CNAME, dns.apex.NS has records, and they are not this name’s: the NS query follows the CNAME to the target’s zone. not_a_zone is the field that answers whether a name is an apex. enclosing_zone for a CNAME names the target’s zone (gist.github.com reports github.com), and is absent when no SOA surfaces (old.reddit.com). Probe the enclosing zone for the zone-level checks.

The number of labels says nothing about the shape of a name. www.cloudflare.com, data.gov.uk and api.openai.com are genuine zone apexes with their own NS records and get the full zone treatment. Whether a name is a registrable domain is a separate question, judged by the Public Suffix List, and it decides web.www: www.cloudflare.com is a zone apex but not a registrable domain, so it reports not_a_zone: false and has no web.www.

Uses

  • A domain is registered but “not working”: separate DNS breakage (NXDOMAIN, lame delegation, DNSSEC bogus), certificate breakage (tls.chain) and web breakage (nothing on 80/443, 5xx) in one call. See also datapulse_help(topic="why_missing").
  • Confirming a nameserver migration: delegation.status and the nameservers audit show whether parent and child agree and every server answers authoritatively with the same serial.
  • Certificate hygiene across a portfolio: tls.chain, cert.days_remaining, cert_consistent, TLS 1.0/1.1 acceptance, caa.hosts.
  • Portfolio audits: run the probe per domain, filter on raw_output.ok, key on raw_output.findings[].code with warn and fail as the actionable severities, and check created_at to confirm each report is from this run.

For plain record lookups, datapulse_live_dns; for registration data, datapulse_live_rdap.

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