ns.lol API

Fast, API-first DNS toolkit. No accounts, no API keys, no tracking.

Base URL: https://ns.lol · JSON endpoint: /api/docs

Quick Start

curl -s https://ns.lol/example.com | jq

Endpoints

GET/:domain
Full DNS report — queries A, AAAA, CNAME, MX, TXT, NS, SOA, SRV, CAA, HTTPS, DS in parallel.
curl -s https://ns.lol/example.com | jq
GET/:domain/:type
Single record type lookup. 55+ named types: a aaaa cname mx txt ns soa srv caa ptr https svcb ds dnskey naptr tlsa sshfp loc hinfo rrsig nsec nsec3 cert uri dname rp openpgpkey smimea and more. Also accepts numeric QTYPEs (1–65535).
curl -s https://ns.lol/example.com/mx | jq
GET/:domain/:number
Custom QTYPE — pass a numeric record type (1–65535).
curl -s https://ns.lol/example.com/65 | jq  # HTTPS record
GET/:domain/any
Simulated ANY query — queries all common types in parallel. RFC 8482 deprecated real ANY; this is the modern equivalent.
curl -s https://ns.lol/example.com/any | jq
GET/:domain/trace
Authority chain walk — traces delegation from root → TLD → authoritative NS → final answer. Shows each hop with nameserver, answer, and timing.
curl -s https://ns.lol/example.com/trace | jq
GET/:ip
Reverse DNS (PTR) lookup for IPv4 or IPv6 addresses.
curl -s https://ns.lol/8.8.8.8 | jq
curl -s https://ns.lol/2606:4700:4700::1111 | jq
GET/:domain/propagation
Global DNS propagation check across 13 resolvers. Real UDP queries via dedicated Fly.io probes — not DoH approximations.
curl -s "https://ns.lol/example.com/propagation?type=MX" | jq
ParamDescription
?type=Record type to check (default: A)
?expected=Expected value — resolvers flagged as matching or divergent
GET/:domain/health
Zone health report with letter grade (A–F). Checks DNSSEC, NS diversity, SOA values, delegation consistency.
curl -s https://ns.lol/example.com/health | jq
GET/:domain/email
Email DNS audit — MX, SPF, DKIM (common selectors), DMARC, MTA-STS, BIMI, DANE/TLSA. Returns a letter grade. Includes deep SPF analysis inline.
curl -s https://ns.lol/example.com/email | jq
GET/:domain/spfNEW
Deep SPF analysis — recursive include tree, lookup budget tracking (X/10), term-by-term plain English explanations, IP range expansion with CIDR counts, issue detection. Follows every include: and redirect= recursively.
curl -s https://ns.lol/example.com/spf | jq
GET/:domain/security
Security analysis — dangling CNAME/NS, NXDOMAIN hijacking, wildcard, CDN/WAF detection, NS diversity, CAA policy.
curl -s https://ns.lol/example.com/security | jq
POST/batch
Batch lookup — query up to 20 domains in one request.
curl -s -X POST https://ns.lol/batch \
  -H 'Content-Type: application/json' \
  -d '{"domains":["google.com","github.com"],"type":"A"}' | jq
GET/api/docs
Machine-readable API documentation (this page in JSON).
curl -s https://ns.lol/api/docs | jq

Query Parameters

ParameterTypeDescription
?explain=truebooleanAdd plain-English explanations to every record and signal. Bypasses cache.
?force=truebooleanBypass cache and force a fresh lookup.
?expected=stringExpected DNS value for propagation — resolvers flagged as matching or divergent.
?type=stringRecord type for propagation checks (default: A).

Content Negotiation

Accept HeaderResponse
application/jsonJSON (default for curl, httpie, wget)
application/dns-jsonAlias for JSON (RFC 8484)
text/plaindig-style plain text output
text/htmlInteractive SPA (default for browsers)

Rate Limiting

120 requests per hour per IP, enforced via Cloudflare Durable Objects with a rolling window. DNS lookups are lightweight, so ns.lol allows more requests than certs.lol (60/hr) where each scan involves a TLS probe.

Rate limits exist for abuse prevention — they keep hosting costs near zero so ns.lol can stay free. Cached results do not count toward the limit.

Every response includes rate limit headers:

HeaderDescription
X-RateLimit-LimitMax requests per window (120)
X-RateLimit-RemainingRequests remaining
X-RateLimit-ResetUnix timestamp when window resets
X-CacheHIT or MISS — whether result came from cache

When exceeded, returns 429 with Retry-After header.

Not rate-limited: /, /health, /docs, /api/docs, /about, /privacy, /terms.

Prefer working in the terminal? Install the CLI — wraps the ns.lol API with a cleaner interface for scripting and automation.

Caching

EndpointCache TTL
Record lookups, full reports1 hour
Health, security checks6 hours
PropagationNever — always live

Bypass with ?force=true or ?explain=true. The X-Cache response header shows HIT or MISS. The _meta.cache_hit field in JSON responses also indicates cache status.

Examples

# Full DNS report
curl -s https://ns.lol/example.com | jq

# Single record type
curl -s https://ns.lol/example.com/mx | jq

# Reverse DNS
curl -s https://ns.lol/8.8.8.8 | jq

# Propagation with expected value
curl -s "https://ns.lol/example.com/propagation?expected=93.184.216.34" | jq

# Zone health with explanations
curl -s "https://ns.lol/example.com/health?explain=true" | jq

# Email DNS audit
curl -s https://ns.lol/example.com/email | jq

# Security analysis
curl -s https://ns.lol/example.com/security | jq

# Authority trace
curl -s https://ns.lol/example.com/trace | jq

# dig-style output
curl -sH "Accept: text/plain" https://ns.lol/example.com

# Batch lookup
curl -s -X POST https://ns.lol/batch \
  -H 'Content-Type: application/json' \
  -d '{"domains":["google.com","github.com"]}' | jq

# Check rate limit headers
curl -si https://ns.lol/example.com 2>&1 | grep X-RateLimit

Infrastructure

Family