# Domain report API

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`

One graded report on a domain: DNS with DNSSEC and nameservers, registration, email setup, SSL and the website's HTTPS and security headers, each with its own grade, plus facts such as age and hosting. Costs 10 credits per call; cached answers cost the same. Calls that fail upstream (502) are free. Answers are cached for up to 5 minutes; send fresh=true to ask the source again. A retry with the same `X-Request-Id` returns the stored result of the first call for 24 hours without charging again, marked with the `X-Replayed: true` header.

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | yes | A domain or URL to report on. |
| `fresh` | boolean | no | Skip the cache and ask the source again; costs the same. |

## Response

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tool` | string | yes |  |
| `target` | string | yes |  |
| `status` | "ok" | "partial" | "error" | yes |  |
| `fetched_at` | string | no |  |
| `cached` | boolean | no |  |
| `credits_used` | integer | no | Credits 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` | string | yes |  |
| `score` | integer or null | no |  |
| `findings` | array of object | no |  |
| `credits_remaining` | integer | yes | Your balance after this call. It can be below zero after a refund; free tools still work then |
| `data` | object | yes | This tool's result |
| `data.name` | string | yes |  |
| `data.unicode` | string | yes |  |
| `data.registrable` | string or null | yes |  |
| `data.grade` | string or null | yes |  |
| `data.sections` | object | yes |  |
| `data.facts` | object or null | yes |  |
| `data.section_order` | array of string | yes |  |

## 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

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

```python
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"])
```

```ts
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:

```json
{
  "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

```json
{
  "tool": "domain_report",
  "arguments": {
    "domain": "example.com"
  }
}
```

```text
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
```
