GET /api/dns-lookup

DNS Lookup

Resolve DNS records for a hostname. Returns A, AAAA, CNAME, MX, TXT, and NS records. Optionally filter to a single record type. Results are cached for 60 seconds.

Query parameters

domainrequiredThe domain to resolve (e.g. example.com).
hostnameoptionalDeprecated alias for 'domain'; still accepted for backwards compatibility. Prefer 'domain'.
typeoptionalFilter to a specific record type: A, AAAA, CNAME, MX, TXT, NS. Omit to return all.

Example requests

curl (all record types)

curl "https://tinyutils.dev/api/dns-lookup?domain=example.com"

curl (MX records only)

curl "https://tinyutils.dev/api/dns-lookup?domain=example.com&type=MX"

JavaScript (fetch)

const res = await fetch(
  "https://tinyutils.dev/api/dns-lookup?domain=example.com"
);
const data = await res.json();

Example response (all types)

{
  "ok": true,
  "hostname": "example.com",
  "normalizedHostname": "example.com",
  "records": {
    "A": ["93.184.216.34"],
    "AAAA": ["2606:2800:21f:cb07:6820:80da:af6b:8b2c"],
    "CNAME": [],
    "MX": [],
    "TXT": ["v=spf1 -all"],
    "NS": ["a.iana-servers.net", "b.iana-servers.net"]
  },
  "meta": {
    "lookupTimeMs": 42,
    "cached": false,
    "rateLimitedScope": "global"
  }
}

Example response (type filter)

{
  "ok": true,
  "hostname": "example.com",
  "normalizedHostname": "example.com",
  "type": "MX",
  "records": {
    "MX": [{ "exchange": "mail.example.com", "priority": 10 }]
  },
  "meta": {
    "lookupTimeMs": 18,
    "cached": false,
    "rateLimitedScope": "global"
  }
}

Error response

{
  "ok": false,
  "error": "DNS_NOT_FOUND"
}

Error codes

INVALID_HOSTNAMEThe hostname is missing, malformed, or is an IP address.
UNSUPPORTED_RECORD_TYPEThe requested record type is not supported.
BLOCKED_HOSTNAMEThe hostname is a private, reserved, or internal address.
DNS_NOT_FOUNDNo DNS records were found for the given hostname and type.
DNS_LOOKUP_FAILEDThe DNS resolution failed unexpectedly.
RATE_LIMITEDYou have exceeded the daily request limit.
INTERNAL_ERRORAn unexpected server error occurred.

Rate limiting

Requests are rate-limited via a global pool shared with url-check and url-resolve. Results are cached for 60 seconds to reduce duplicate lookups. When the limit is exceeded, the endpoint returns HTTP 429 with RATE_LIMITED.

Batch endpoint

Look up to 10 domains in a single request.

MethodPOST
Path/api/dns-lookup/batch

curl

curl -X POST "https://tinyutils.dev/api/dns-lookup/batch" \
  -H "Content-Type: application/json" \
  -d '{"domains":["example.com","openai.com"]}'

JavaScript (fetch)

const res = await fetch("https://tinyutils.dev/api/dns-lookup/batch", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ domains: ["example.com", "openai.com"] }),
});
const data = await res.json();

See also

Looking for use-case guidance? DNS Lookup API walks through common lookup scenarios and integration patterns.