Docs menu

Domain report

One report on a domain's DNS, registration, email setup and certificate, each with its own grade.

GET /v1/report

Price
Costs 10 credits per call; cached answers cost the same. Calls that fail upstream (502) are free.
Cache
Answers are cached for up to 5 minutes; send fresh=true to ask the source again.
MCP tool
domain_report

Run it in the browser

Query parameters

Query parameters
NameTypeDescription
domain (required)stringA domain or URL to report on.
freshbooleanSkip the cache and ask the source again; costs the same.

Response

Response fields
NameTypeDescription
tool (required)string
target (required)string
status (required)"ok" | "partial" | "error"
fetched_atstring
cachedboolean
credits_usedintegerCredits this call took from your balance. 0 for free tools, for a replay of an earlier call, and for a free check run on the website without signing in
summary (required)string
scoreinteger or null
findingsarray of object
credits_remaining (required)integerYour balance after this call. It can be below zero after a refund; free tools still work then
data (required)objectThis tool's result
data.name (required)string
data.unicode (required)string
data.registrable (required)string or null
data.grade (required)string or null
data.sections (required)object
data.facts (required)object or null
data.section_order (required)array of string

Errors

  • 400 Invalid domain, URL or parameter, a TLD this tool can't check, or an X-Request-Id already used for another call (`invalid_domain`, `invalid_url`, `invalid_request`, `unsupported_tld`)
  • 401 Missing, unknown or revoked API key, or one whose creator is no longer a member of the account (`unauthorized`)
  • 402 Balance below the call's price (`insufficient_credits`)
  • 403 Account suspended, the key's creator is over the plan's seats, or an anonymous check without a valid proof-of-work or for a tool that needs an account, or bulk checks before a first purchase (`account_suspended`, `plan_limit`, `challenge_required`, `sign_in_required`, `bulk_locked`)
  • 429 Too many requests, today's free checks are used up, or too many website scans at once; wait for the number of seconds in the Retry-After header (`rate_limited`, `free_limit_reached`, `too_many_jobs`). Not charged
  • 500 Unexpected error (`internal_error`)
  • 502 Every upstream source failed; not charged (`source_unavailable`). A Retry-After header says how long to wait when the source asked us to

Example

curl

curl
curl "https://api.dnssuper.com/v1/report?domain=example.com" \
  -H "Authorization: Bearer $DNSSUPER_API_KEY"

Python

Python (httpx)
import os

import httpx

client = httpx.Client(
    base_url="https://api.dnssuper.com",
    headers={"Authorization": f"Bearer {os.environ['DNSSUPER_API_KEY']}"},
    timeout=60,
)
response = client.get("/v1/report", params={
    "domain": "example.com",
})
response.raise_for_status()
result = response.json()
print(result["summary"], result["credits_used"])

TypeScript

TypeScript (fetch)
const response = await fetch(`https://api.dnssuper.com/v1/report?${new URLSearchParams({"domain":"example.com"})}`, {
  headers: { Authorization: `Bearer ${process.env.DNSSUPER_API_KEY}` },
});
if (!response.ok) throw new Error((await response.json()).error.message);
const result = await response.json();
console.log(result.summary, result.credits_used);
Example response
Example response
{
  "tool": "domain-report",
  "target": "example.com",
  "status": "ok",
  "fetched_at": "2026-11-14T10:00:00Z",
  "cached": false,
  "credits_used": 10,
  "summary": "example.com gets an A. HSTS isn't set and your DMARC policy only monitors (p=none). DNS and registration look fine.",
  "score": 91,
  "findings": [
    {
      "id": "hsts.missing",
      "severity": "fail",
      "title": "HSTS isn't set",
      "detail": "https://example.com/ sends no Strict-Transport-Security.",
      "fix": "Send Strict-Transport-Security: max-age=31536000; includeSubDomains over HTTPS."
    },
    {
      "id": "dmarc.policy_none",
      "severity": "warn",
      "title": "Your DMARC policy only monitors (p=none)",
      "detail": "_dmarc.example.com says p=none.",
      "fix": "Move to p=quarantine, then p=reject, once reports show your mail passes."
    },
    {
      "id": "spf.softfail_all",
      "severity": "warn",
      "title": "Your SPF record ends in ~all",
      "detail": "With p=none, ~all lets spoofed mail through.",
      "fix": "Move to -all once DMARC reports show all your mail passes."
    },
    {
      "id": "ssl.expires_soon",
      "severity": "warn",
      "title": "Your certificate expires within 30 days",
      "detail": "The certificate on example.com and www.example.com expires on 26 November 2026.",
      "fix": "Renew the certificate or check that automatic renewal is set up."
    },
    {
      "id": "dns.no_caa",
      "severity": "info",
      "title": "Your domain has no CAA record",
      "detail": "Any certificate authority may issue certificates for example.com.",
      "fix": "Add a CAA record naming the certificate authorities you use, for example 0 issue \"letsencrypt.org\", so no other authority will issue certificates for your domain."
    },
    {
      "id": "dnssec.unsigned",
      "severity": "info",
      "title": "Your domain isn't signed with DNSSEC",
      "detail": "There is no DS record for example.com at the .com registry and no DNSKEY in the zone.",
      "fix": "Turn on DNSSEC at your DNS provider, then add the DS record it gives you at your registrar."
    },
    {
      "id": "ns.consistent",
      "severity": "pass",
      "title": "Your nameservers all answer and agree",
      "detail": "2 nameservers, 2 addresses, serial 2026111401 everywhere.",
      "fix": "Nothing to do."
    },
    {
      "id": "mx.ok",
      "severity": "pass",
      "title": "Your mail servers are set up",
      "detail": "1 MX host, smtp.google.com, resolves.",
      "fix": "Nothing to do."
    },
    {
      "id": "dkim.found",
      "severity": "pass",
      "title": "DKIM keys found",
      "detail": "Selector google has a 2048-bit RSA key.",
      "fix": "Nothing to do."
    }
  ],
  "data": {
    "name": "example.com",
    "unicode": "example.com",
    "registrable": "example.com",
    "grade": "A",
    "sections": {
      "dns": {
        "section": "dns",
        "status": "ok",
        "score": 100,
        "grade": "A",
        "summary": "example.com resolves to 1 IPv4 and 1 IPv6 address, receives mail through 1 MX host and isn't DNSSEC-signed. example.com isn't signed with DNSSEC. Both of its nameservers answer and agree.",
        "checks": [
          {
            "tool": "dns-lookup",
            "status": "ok",
            "cached": false,
            "fetched_at": "2026-11-14T10:00:00Z",
            "summary": "example.com resolves to 1 IPv4 and 1 IPv6 address, receives mail through 1 MX host and isn't DNSSEC-signed.",
            "findings": [
              {
                "id": "dns.no_caa",
                "severity": "info",
                "title": "Your domain has no CAA record",
                "detail": "Any certificate authority may issue certificates for example.com.",
                "fix": "Add a CAA record naming the certificate authorities you use, for example 0 issue \"letsencrypt.org\", so no other authority will issue certificates for your domain."
              }
            ],
            "data": {
              "name": "example.com",
              "unicode": "example.com",
              "nxdomain": false,
              "dnssec": "insecure",
              "wildcard": false,
              "records": {
                "A": [
                  {
                    "name": "example.com",
                    "ttl": 300,
                    "value": "192.0.2.10"
                  }
                ],
                "AAAA": [
                  {
                    "name": "example.com",
                    "ttl": 300,
                    "value": "2001:db8::10"
                  }
                ],
                "CNAME": [],
                "MX": [
                  {
                    "name": "example.com",
                    "ttl": 3600,
                    "value": "1 smtp.google.com"
                  }
                ],
                "NS": [
                  {
                    "name": "example.com",
                    "ttl": 86400,
                    "value": "anna.ns.cloudflare.com"
                  },
                  {
                    "name": "example.com",
                    "ttl": 86400,
                    "value": "bob.ns.cloudflare.com"
                  }
                ],
                "TXT": [
                  {
                    "name": "example.com",
                    "ttl": 3600,
                    "value": "v=spf1 include:_spf.google.com ~all"
                  }
                ],
                "SOA": [
                  {
                    "name": "example.com",
                    "ttl": 3600,
                    "value": "anna.ns.cloudflare.com dns.cloudflare.com 2026111401 10000 2400 604800 1800"
                  }
                ],
                "CAA": []
              },
              "query_status": {
                "A": "ok",
                "AAAA": "ok",
                "CNAME": "nodata",
                "MX": "ok",
                "NS": "ok",
                "TXT": "ok",
                "SOA": "ok",
                "CAA": "nodata"
              },
              "cname_chain": [],
              "hosts": {
                "smtp.google.com": {
                  "A": [
                    "192.0.2.25"
                  ],
                  "AAAA": [],
                  "roles": [
                    "MX"
                  ],
                  "status": "ok"
                },
                "anna.ns.cloudflare.com": {
                  "A": [
                    "198.51.100.1"
                  ],
                  "AAAA": [],
                  "roles": [
                    "NS"
                  ],
                  "status": "ok"
                },
                "bob.ns.cloudflare.com": {
                  "A": [
                    "198.51.100.2"
                  ],
                  "AAAA": [],
                  "roles": [
                    "NS"
                  ],
                  "status": "ok"
                }
              },
              "min_ttl": 300
            }
          },
          {
            "tool": "dnssec-checker",
            "status": "ok",
            "cached": false,
            "fetched_at": "2026-11-14T10:00:00Z",
            "summary": "example.com isn't signed with DNSSEC. Both of its nameservers answer and agree.",
            "findings": [
              {
                "id": "dnssec.unsigned",
                "severity": "info",
                "title": "Your domain isn't signed with DNSSEC",
                "detail": "There is no DS record for example.com at the .com registry and no DNSKEY in the zone.",
                "fix": "Turn on DNSSEC at your DNS provider, then add the DS record it gives you at your registrar."
              },
              {
                "id": "ns.consistent",
                "severity": "pass",
                "title": "Your nameservers all answer and agree",
                "detail": "2 nameservers, 2 addresses, serial 2026111401 everywhere.",
                "fix": "Nothing to do."
              }
            ],
            "data": {
              "name": "example.com",
              "unicode": "example.com",
              "zone": "example.com",
              "parent": "com",
              "dnssec": "insecure",
              "extended_errors": [],
              "chain": [
                {
                  "zone": "com",
                  "signed": true,
                  "secure": true
                },
                {
                  "zone": "example.com",
                  "signed": false,
                  "secure": false
                }
              ],
              "ds": [],
              "dnskeys": [],
              "signatures": [],
              "parent_ns": [
                "anna.ns.cloudflare.com",
                "bob.ns.cloudflare.com"
              ],
              "parent_ns_ttl": 172800,
              "child_ns": [
                "anna.ns.cloudflare.com",
                "bob.ns.cloudflare.com"
              ],
              "nameservers": [
                {
                  "name": "anna.ns.cloudflare.com",
                  "in_parent": true,
                  "in_child": true,
                  "glue": [],
                  "addresses": [
                    "198.51.100.1"
                  ],
                  "status": "ok",
                  "servers": []
                },
                {
                  "name": "bob.ns.cloudflare.com",
                  "in_parent": true,
                  "in_child": true,
                  "glue": [],
                  "addresses": [
                    "198.51.100.2"
                  ],
                  "status": "ok",
                  "servers": []
                }
              ],
              "serials": {
                "2026111401": [
                  "198.51.100.1",
                  "198.51.100.2"
                ]
              },
              "ipv6_checked": false,
              "min_ttl": 300
            }
          }
        ]
      },
      "registration": {
        "section": "registration",
        "status": "ok",
        "score": 100,
        "grade": "A",
        "summary": "example.com is registered with Example Registrar, Inc. until 13 August 2027 (in 272 days). Transfers are locked.",
        "checks": [
          {
            "tool": "whois-lookup",
            "status": "ok",
            "cached": false,
            "fetched_at": "2026-11-14T10:00:00Z",
            "summary": "example.com is registered with Example Registrar, Inc. until 13 August 2027 (in 272 days). Transfers are locked.",
            "findings": [],
            "data": {
              "name": "example.com",
              "unicode": "example.com",
              "tld": "com",
              "tier": "A",
              "source": "rdap",
              "registered": true,
              "registrar": {
                "name": "Example Registrar, Inc.",
                "iana_id": "9999",
                "url": "https://registrar.example.net",
                "abuse_email": "abuse@registrar.example.net"
              },
              "created": "1995-08-14T04:00:00Z",
              "updated": "2026-08-14T07:01:34Z",
              "expires": "2027-08-13T04:00:00Z",
              "age_days": 11415,
              "days_to_expiry": 272,
              "statuses": [
                "clientDeleteProhibited",
                "clientTransferProhibited",
                "clientUpdateProhibited"
              ],
              "nameservers": [
                "anna.ns.cloudflare.com",
                "bob.ns.cloudflare.com"
              ],
              "dnssec": false,
              "redacted_fields": [
                "registrant",
                "admin",
                "tech"
              ],
              "unpublished_fields": []
            }
          }
        ]
      },
      "email": {
        "section": "email",
        "status": "ok",
        "score": 87,
        "grade": "B",
        "summary": "example.com receives mail through Google Workspace and signs it with DKIM. Its DMARC policy only monitors, so spoofed mail isn't blocked yet.",
        "checks": [
          {
            "tool": "email-checker",
            "status": "ok",
            "cached": false,
            "fetched_at": "2026-11-14T10:00:00Z",
            "summary": "example.com receives mail through Google Workspace and signs it with DKIM. Its DMARC policy only monitors, so spoofed mail isn't blocked yet.",
            "score": 87,
            "findings": [
              {
                "id": "dmarc.policy_none",
                "severity": "warn",
                "title": "Your DMARC policy only monitors (p=none)",
                "detail": "_dmarc.example.com says p=none.",
                "fix": "Move to p=quarantine, then p=reject, once reports show your mail passes."
              },
              {
                "id": "spf.softfail_all",
                "severity": "warn",
                "title": "Your SPF record ends in ~all",
                "detail": "With p=none, ~all lets spoofed mail through.",
                "fix": "Move to -all once DMARC reports show all your mail passes."
              },
              {
                "id": "mx.ok",
                "severity": "pass",
                "title": "Your mail servers are set up",
                "detail": "1 MX host, smtp.google.com, resolves.",
                "fix": "Nothing to do."
              },
              {
                "id": "dkim.found",
                "severity": "pass",
                "title": "DKIM keys found",
                "detail": "Selector google has a 2048-bit RSA key.",
                "fix": "Nothing to do."
              }
            ],
            "data": {
              "name": "example.com",
              "unicode": "example.com",
              "nxdomain": false,
              "providers": [
                {
                  "id": "google-workspace",
                  "name": "Google Workspace",
                  "source": "mx"
                }
              ],
              "mx": {
                "status": "ok",
                "null_mx": false,
                "implicit": false,
                "records": [
                  {
                    "preference": 1,
                    "host": "smtp.google.com",
                    "ttl": 3600,
                    "is_ip": false,
                    "A": [
                      "192.0.2.25"
                    ],
                    "AAAA": [],
                    "status": "ok",
                    "provider": "google-workspace"
                  }
                ]
              },
              "spf": {
                "status": "found",
                "record": "v=spf1 include:_spf.google.com ~all",
                "records": [
                  "v=spf1 include:_spf.google.com ~all"
                ],
                "all": "~all",
                "lookups": 4,
                "lookup_limit": 10,
                "void_lookups": 0,
                "capped": false
              },
              "dmarc": {
                "status": "found",
                "name": "_dmarc.example.com",
                "source": "exact",
                "record": "v=DMARC1; p=none; rua=mailto:dmarc@example.com",
                "policy": "none",
                "effective_policy": "none",
                "pct": 100,
                "adkim": "r",
                "aspf": "r",
                "reports": [
                  {
                    "kind": "rua",
                    "uri": "mailto:dmarc@example.com",
                    "domain": "example.com",
                    "external": false
                  }
                ]
              },
              "dkim": {
                "selectors_tried": [
                  "google",
                  "default",
                  "selector1",
                  "selector2"
                ],
                "failed": [],
                "found": [
                  {
                    "selector": "google",
                    "name": "google._domainkey.example.com",
                    "status": "ok",
                    "key_type": "rsa",
                    "key_bits": 2048,
                    "testing": false,
                    "provider": "google-workspace",
                    "record": "v=DKIM1; k=rsa; p=MIIBIjANBgkqh..."
                  }
                ]
              },
              "policies": {
                "mta_sts": {
                  "present": false
                },
                "tls_rpt": {
                  "present": false
                },
                "bimi": {
                  "present": false
                }
              },
              "min_ttl": 300
            }
          }
        ]
      },
      "ssl": {
        "section": "ssl",
        "status": "ok",
        "score": 90,
        "grade": "A",
        "summary": "example.com's certificate is trusted and valid for 12 more days, covering example.com and www.example.com. The server offers TLS 1.3.",
        "checks": [
          {
            "tool": "ssl-checker",
            "status": "ok",
            "cached": false,
            "fetched_at": "2026-11-14T10:00:00Z",
            "summary": "example.com's certificate is trusted and valid for 12 more days, covering example.com and www.example.com. The server offers TLS 1.3.",
            "score": 90,
            "findings": [
              {
                "id": "ssl.expires_soon",
                "severity": "warn",
                "title": "Your certificate expires within 30 days",
                "detail": "The certificate on example.com and www.example.com expires on 26 November 2026.",
                "fix": "Renew the certificate or check that automatic renewal is set up."
              }
            ],
            "data": {
              "name": "example.com",
              "unicode": "example.com",
              "hosts": [
                {
                  "host": "example.com",
                  "status": "ok",
                  "address": "192.0.2.10",
                  "tls": {
                    "version": "TLSv1.3",
                    "cipher": "TLS_AES_128_GCM_SHA256",
                    "forward_secrecy": true,
                    "alpn": "h2",
                    "versions": {
                      "TLSv1.3": true,
                      "TLSv1.2": true
                    },
                    "non_forward_secret": false,
                    "ocsp_stapled": false
                  },
                  "certificate": {
                    "subject": "CN=example.com",
                    "common_name": "example.com",
                    "names": [
                      "example.com",
                      "www.example.com"
                    ],
                    "issuer": "CN=R11,O=Let's Encrypt,C=US",
                    "issuer_org": "Let's Encrypt",
                    "caa_identifiers": [
                      "letsencrypt.org"
                    ],
                    "serial": "04a1",
                    "not_before": "2026-08-28T00:00:00Z",
                    "not_after": "2026-11-26T23:59:59Z",
                    "days_left": 12,
                    "key": {
                      "type": "EC",
                      "size": 256,
                      "curve": "secp256r1"
                    },
                    "signature_algorithm": "sha256WithRSAEncryption",
                    "sha256": "ab12",
                    "scts": 2
                  },
                  "chain": [],
                  "trust": {
                    "trusted": true,
                    "hostname_match": true,
                    "root": "ISRG Root X1",
                    "path": [
                      "example.com",
                      "R11",
                      "ISRG Root X1"
                    ]
                  }
                },
                {
                  "host": "www.example.com",
                  "status": "ok",
                  "address": "192.0.2.10",
                  "chain": [],
                  "trust": {
                    "trusted": true,
                    "hostname_match": true,
                    "root": "ISRG Root X1",
                    "path": []
                  }
                }
              ],
              "trust_store": {
                "source": "certifi",
                "version": "2026.10.5"
              },
              "legacy_versions_tested": true
            }
          }
        ]
      },
      "website": {
        "section": "website",
        "status": "ok",
        "score": 80,
        "grade": "B",
        "summary": "example.com gets a B for its HTTP headers. HSTS is missing.",
        "checks": [
          {
            "tool": "security-headers",
            "status": "ok",
            "cached": false,
            "fetched_at": "2026-11-14T10:00:00Z",
            "summary": "example.com gets a B for its HTTP headers. HSTS is missing.",
            "score": 80,
            "findings": [
              {
                "id": "hsts.missing",
                "severity": "fail",
                "title": "HSTS isn't set",
                "detail": "https://example.com/ sends no Strict-Transport-Security.",
                "fix": "Send Strict-Transport-Security: max-age=31536000; includeSubDomains over HTTPS."
              }
            ],
            "data": {
              "host": "example.com",
              "alternate_host": "www.example.com",
              "reachable": true,
              "no_website": false,
              "entry_points": []
            }
          }
        ]
      }
    },
    "facts": {
      "domain_age_days": 11415,
      "created": "1995-08-14T04:00:00Z",
      "expires": "2027-08-13T04:00:00Z",
      "days_to_expiry": 272,
      "registrar": "Example Registrar, Inc.",
      "dns_host": {
        "id": "cloudflare",
        "name": "Cloudflare",
        "source": "ns"
      },
      "mail_provider": {
        "id": "google-workspace",
        "name": "Google Workspace",
        "source": "mx"
      },
      "web_host": {
        "id": "vercel",
        "name": "Vercel",
        "source": "cname"
      },
      "addresses": [
        "192.0.2.10",
        "2001:db8::10"
      ],
      "network": {
        "asn": 64496,
        "name": "EXAMPLE-NET",
        "country": "NL"
      }
    },
    "section_order": [
      "dns",
      "registration",
      "email",
      "facts",
      "website",
      "ssl"
    ]
  },
  "credits_remaining": 498
}

MCP

MCP tool call
{
  "tool": "domain_report",
  "arguments": {
    "domain": "example.com"
  }
}
Compact MCP output
example.com gets an A. HSTS isn't set and your DMARC policy only monitors (p=none). DNS and registration look fine.
Score: 91/100
Grade: A
DNS: A. example.com resolves to 1 IPv4 and 1 IPv6 address, receives mail through 1 MX host and isn't DNSSEC-signed.
Registration: A. example.com is registered with Example Registrar, Inc. until 13 August 2027 (in 272 days).
Email: B. example.com receives mail through Google Workspace and signs it with DKIM.
SSL: A. example.com's certificate is trusted and valid for 12 more days, covering example.com and www.example.com.
Website: B. example.com gets a B for its HTTP headers.
Facts: registered 1995-08-14 (11415 days ago); expires 2027-08-13 (in 272 days); registrar Example Registrar, Inc.; DNS Cloudflare; mail Google Workspace; web Vercel; addresses 192.0.2.10, 2001:db8...
- fail: HSTS isn't set. Fix: Send Strict-Transport-Security: max-age=31536000; includeSubDomains over HTTPS.
- warn: Your DMARC policy only monitors (p=none). Fix: Move to p=quarantine, then p=reject, once reports show your mail passes.
- warn: Your SPF record ends in ~all. Fix: Move to -all once DMARC reports show all your mail passes.
- warn: Your certificate expires within 30 days. Fix: Renew the certificate or check that automatic renewal is set up.
+2 more findings (pass detail='full' to see all)
3 checks passed
Credits: 10 credits used, 498 remaining | fresh | checked 2026-11-14 10:00 UTC