DNS.Tools API

Built for developers who need fast, reliable, and accurate domain and website intelligence. Our platform abstracts away the complexities of DNS, WHOIS, and RDAP so you can focus on building reliable applications.

The API uses RESTful principles and returns JSON responses. Queries are made over HTTPS with simple GET requests. All endpoint URLs use the following pattern:

API Endpoint Pattern

GET https://api.dns.tools/v1/{tool}/{query}?{parameters}

Additional resources for working with the DNS.Tools API:

Authentication

Free Tier (No API Key)

We offer a generous free tier that requires no authentication, so you can start using the API immediately. Please contact us for an API Key to access higher rate limits.

You can begin using the API without registration or authentication. The free tier is perfect for testing and light usage.

GET

API Key Authentication

For higher rate limits and production use, you can authenticate using an API key. We support three methods of providing your API key:

Header Authentication Methods

X-API-Key: YOUR-API-KEYheader

Provide your API key in an HTTP request header.

Authorization: Bearer YOUR-API-KEYheader

Authenticate using standard Bearer token format.

Query Parameter Authentication

?key=YOUR-API-KEYquerystring

Provide your API key as a URL query parameter.

Example Authenticated Requests

Authentication Examples

# Using X-API-Key Header
curl -X GET "https://api.dns.tools/v1/domain/google.com" \
  -H "X-API-Key: YOUR-API-KEY"
  
# Using Authorization Bearer Token
curl -X GET "https://api.dns.tools/v1/domain/google.com" \
  -H "Authorization: Bearer YOUR-API-KEY"
  
# Using Query Parameter
curl -X GET "https://api.dns.tools/v1/domain/google.com?key=YOUR-API-KEY"

JavaScript Fetch Example

const response = await fetch('https://api.dns.tools/v1/domain/google.com', {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR-API-KEY'
    // or with Authorization Bearer Token (don't need both)
    // 'Authorization: Bearer YOUR-API-KEY'
  }
});

const data = await response.json();

Making Requests

All API requests are made using simple GET requests. The API follows a simple RESTful URL structure where the tool and query are specified in the path, with optional parameters provided as query strings. All endpoints use the following URL pattern:

API Endpoint Pattern

curl -X GET "https://api.dns.tools/v1/{tool}/{query}?{parameters}"

API Endpoint Components

toolstringrequired

The specific API tool to use for analysis. Not all tools are currently supported through the API.

Examples:dnsdomain

querystringrequired

The domain name, hostname, IP address, or other query target. International domain names (IDN) can be provided in either Unicode or Punycode format.

Examples:google.comsub.domain.comбилеты.сайт192.168.72.1

?{parameters}querystring

Additional query parameters to pass to the tool. See the tool-specific documentation for all available tool options.

Examples:type=Aserver=8.8.8.8dnssec=true

Response Format

All API responses follow a consistent JSON structure and share common request metadata fields with a results array containing the tool-specific results. Successful responses return HTTP 200 status codes, while errors return appropriate 4xx or 5xx status codes with detailed error information. (See Errors below.)

API Response Example

{
  "tool": "dns",
  "query": "google.com",
  "requestId": "a7f9c2d4-8e1b-4c3a-9f6e-2d8b5e7c1a9f",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "elapsed": 35,
  "errorCode": null,
  "errorName": null,
  "errorMessage": null,
  "results": [
    {
      // tool-specific data
    }
  ]
}

Common Response Fields

toolstring

The API tool that was used to process the request.

Examples:dnsdomain

querystring

The original query that was submitted to the API.

Examples:google.comsub.domain.comбилеты.сайт192.168.72.1

requestIdstring

A unique identifier for this request, useful for debugging and support.

Examples:a7f9c2d4-8e1b-4c3a-9f6e-2d8b5e7c1a9f

timestampstring

The timestamp when the request was processed, in ISO 8601 format.

Examples:2025-01-15T10:30:00.000Z

elapsednumber

The time taken to process the request in milliseconds.

cachedboolean

Whether the request was served from cache. By default we cache results for up to 24 hours.

Examples:truefalse

resultsarraynullable

An array containing the tool-specific data.

Examples:[{...}]

errorCodenumbernullable

An HTTP status code for the error, or null for successful requests.

Examples:400401429500

errorNamestringnullable

Human-readable error name, or null for successful requests.

Examples:Invalid QueryUnauthorizedToo Many Requests

errorMessagestringnullable

Detailed error message, or null for successful requests.

Examples:The provided query is not a valid domain name

Rate Limits

We implement rate limiting to maintain service quality for all users. Rate limits depend on your usage tier, and are applied per IP address for the Free Tier and per API key for authenticated requests. If the limit is exceeded, your access will be throttled and the API will return a 429 status code. Implement incremental backoff in your retry logic and consider spreading requests over time to avoid exceeding the limit.

Need higher rate limits? Contact us at support@dns.tools to discuss your requirements and get access to a higher tier. We also offer custom solutions for high-volume users and enterprise customers.

Errors

When an error occurs, the API returns an appropriate HTTP status code along with the same JSON structure as successful responses, but with the error fields populated with details and the results set to null.

HTTP Status Codes

200
OK
Request was successful. The response contains the requested data in the results field.
400
Bad Request
Invalid tool, query, or parameters. Check the URL structure and parameter values.
401
Unauthorized
Invalid, missing, or expired API key. Verify your API key is correct and your account is active.
429
Too Many Requests
Rate limit exceeded. Wait before making more requests or upgrade for increased limits.
500
Internal Server Error
An unexpected error occurred while processing your request. Please try again later or contact support with the requestId. You can reach us at support@dns.tools.

Check both the HTTP status code and the errorCode field in the response. Implement retry logic with incremental backoff for transient errors (5xx status codes).

Error Response Example

{
  "tool": "dns",
  "query": "invalid-domain.nope",
  "requestId": "b3e8f1a6-7c2d-4b9e-8f5a-3c6d9e4f2b8c",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "elapsed": 125,
  "errorCode": 400,
  "errorName": "Invalid Query",
  "errorMessage": "The provided query is not a valid domain name",
  "results": null
}

DNS Lookup API

The DNS Lookup API provides comprehensive DNS query support with 30+ record types, custom server support, multiple transport protocols (UDP/TCP), DNSSEC validation, authoritative server queries, and optional detailed diagnostic tracing. It's ideal for DNS monitoring, troubleshooting, and analysis; or just an easy and reliable way to fetch all DNS records using HTTPS.

GET

DNS Query Parameters

typestring

The type of DNS record type to query, or ALL for all common record types.

Default:ALLExamples:ALLSOANSAAAAACNAMEDNAMEMXTXTCAATLSADSDNSKEYRRSIGNSECNSEC3NSEC3PARAMCDSCDNSKEYKEYSIGSRVHTTPSSVCBCERTHINFOTSIGOPENPGPKEYRPSSHFPURINAPTRLOCPTR

serverstring

DNS server to use for queries, or authoritative for authoritative server queries.

Default:authoritativeExamples:authoritative1.1.1.18.8.8.8

recursiveboolean

Enable recursive resolution. Some public servers require or ignore this.Authoritative queries always have server-based recursion disabled as we do the resolution ourselves.

Default:trueExamples:truefalse

dnssecboolean

Enable DNSSEC validation and return additional DNSSEC records. Some nameservers do not support this and will return errors.

Default:falseExamples:truefalse

transportstring

The DNS transport protocol to use. TCP allows larger responses, UDP is faster.

Default:tcpExamples:tcpudp

DNS Request Examples

# Query Specific Record Type
curl -X GET "https://api.dns.tools/v1/dns/google.com?type=MX"
                  
# Use Custom DNS Server
curl -X GET "https://api.dns.tools/v1/dns/google.com?server=ns1.google.com"

# Enable DNSSEC Validation and extra DNSSEC Records
curl -X GET "https://api.dns.tools/v1/dns/google.com?dnssec=true"

JavaScript Fetch Example

const response = await fetch('https://api.dns.tools/v1/dns/x.com?type=A', {
  method: 'GET',
  headers: {
    // set API key if you have one
    'X-API-Key': 'YOUR-API-KEY'
  }
});

const data = await response.json();
if (!response.ok || data.errorCode) {
  console.error('Error:', data.errorMessage || response.status);
} else if (data.results?.length > 0) {
  console.log('First result:', data.results[0]);
}

DNS Response Example

{
  "tool": "dns",
  "query": "google.com",
  "queryType": "ALL",
  "server": "216.239.32.10",
  "serverHost": "ns1.google.com",
  "serverType": "authoritative",
  "transport": "tcp",
  "recursive": false,
  "dnssec": false,
  "requestId": "42187e92-5db4-421c-aaf9-6a75c8091eed",
  "timestamp": "2025-10-03T12:49:45.003Z",
  "elapsed": 315,
  "results": [
    {
      "expire": 1800,
      "hostmaster": "dns-admin.google.com",
      "minttl": 60,
      "name": "google.com",
      "nsname": "ns1.google.com",
      "refresh": 900,
      "retry": 900,
      "serial": 813711196,
      "ttl": 60,
      "type": "SOA"
    },
    {
      "name": "google.com",
      "ttl": 345600,
      "type": "NS",
      "value": "ns1.google.com"
    },
    {
      "name": "google.com",
      "ttl": 345600,
      "type": "NS",
      "value": "ns2.google.com"
    },
    {
      "name": "google.com",
      "ttl": 345600,
      "type": "NS",
      "value": "ns3.google.com"
    },
    {
      "name": "google.com",
      "ttl": 345600,
      "type": "NS",
      "value": "ns4.google.com"
    },
    {
      "address": "142.251.214.142",
      "name": "google.com",
      "ttl": 300,
      "type": "A"
    },
    {
      "address": "2607:f8b0:4005:814::200e",
      "name": "google.com",
      "ttl": 300,
      "type": "AAAA"
    },
    {
      "exchange": "smtp.google.com",
      "name": "google.com",
      "priority": 10,
      "ttl": 300,
      "type": "MX"
    },
    {
      "name": "google.com",
      "ttl": 3600,
      "type": "TXT",
      "value": "apple-domain-verification=30afIBcvSuDV2PLX"
    },
    {
      "name": "google.com",
      "ttl": 3600,
      "type": "TXT",
      "value": "cisco-ci-domain-verification=47c38bc8c4b74b7233e9053220c1bbe76bcc1cd33c7acf7acd36cd6a5332004b"
    },
    {
      "name": "google.com",
      "ttl": 3600,
      "type": "TXT",
      "value": "docusign=1b0a6754-49b1-4db5-8540-d2c12664b289"
    },
    {
      "name": "google.com",
      "ttl": 3600,
      "type": "TXT",
      "value": "docusign=05958488-4752-4ef2-95eb-aa7ba8a3bd0e"
    },
    {
      "name": "google.com",
      "ttl": 3600,
      "type": "TXT",
      "value": "facebook-domain-verification=22rm551cu4k0ab0bxsw536tlds4h95"
    },
    {
      "name": "google.com",
      "ttl": 3600,
      "type": "TXT",
      "value": "globalsign-smime-dv=CDYX+XFHUw2wml6/Gb8+59BsH31KzUr6c1l2BPvqKX8="
    },
    {
      "name": "google.com",
      "ttl": 3600,
      "type": "TXT",
      "value": "google-site-verification=4ibFUgB-wXLQ_S7vsXVomSTVamuOXBiVAzpR5IZ87D0"
    },
    {
      "name": "google.com",
      "ttl": 3600,
      "type": "TXT",
      "value": "google-site-verification=TV9-DBe4R80X4v0M4U_bd_J9cpOJM0nikft0jAgjmsQ"
    },
    {
      "name": "google.com",
      "ttl": 3600,
      "type": "TXT",
      "value": "google-site-verification=wD8N7i1JTNTkezJ49swvWW48f8_9xveREV4oB-0Hf5o"
    },
    {
      "name": "google.com",
      "ttl": 3600,
      "type": "TXT",
      "value": "MS=E4A68B9AB2BB9670BCE15412F62916164C0B20BB"
    },
    {
      "name": "google.com",
      "ttl": 3600,
      "type": "TXT",
      "value": "onetrust-domain-verification=de01ed21f2fa4d8781cbc3ffb89cf4ef"
    },
    {
      "name": "google.com",
      "ttl": 3600,
      "type": "TXT",
      "value": "v=spf1 include:_spf.google.com ~all"
    }
  ]
}

Domain Lookup API

The Domain API provides comprehensive domain registration data by automatically selecting the best data source (RDAP or WHOIS), providing the most complete information possible. Fields with redacted or privacy-protected data are left null and all other fields have normalized formatting.

GET

Domain Request Examples

# Getting domain data for google.com
curl -X GET "https://api.dns.tools/v1/domain/google.com"
                  
# International Domain (IDN) using Punycode
curl -X GET "https://api.dns.tools/v1/domain/xn--jlq480n2rg.xn--fiq228c5hs"

# or use Unicode directly
curl -X GET "https://api.dns.tools/v1/domain/亚马逊.中文网"

JavaScript Fetch Example

const response = await fetch('https://api.dns.tools/v1/domain/google.com', {
  method: 'GET',
  headers: {
    // set API key if you have one
    'X-API-Key': 'YOUR-API-KEY'
  }
});

const data = await response.json();
if (!response.ok || data.errorCode) {
  console.error('Error:', data.errorMessage || response.status);
} else if (data.results?.length > 0) {
  console.log('First result:', data.results[0]);
}

Domain Response Example

{
  "tool": "domain",
  "query": "google.com",
  "requestId": "a016aba0-d199-4c27-89f4-91e4dc69585e",
  "timestamp": "2025-09-30T07:09:59.097Z",
  "elapsed": 22,
  "errorCode": null,
  "errorName": null,
  "errorMessage": null,
  "results": [
    {
      "domain_name": "google.com",
      "domain_name_unicode": null,
      "creation_date": "1997-09-15T07:00:00.000+00:00",
      "expiration_date": "2028-09-13T07:00:00.000+00:00",
      "updated_date": "2024-08-02T02:17:33.000+00:00",
      "nameservers": [
        "ns1.google.com",
        "ns2.google.com",
        "ns3.google.com",
        "ns4.google.com"
      ],
      "dnssec": false,
      "status": [
        "clientUpdateProhibited",
        "clientTransferProhibited",
        "clientDeleteProhibited",
        "serverUpdateProhibited",
        "serverTransferProhibited",
        "serverDeleteProhibited"
      ],
      "registrar": {
        "iana_id": 292,
        "name": "Markmonitor Inc.",
        "address": [
          "3540 E Longwing Ln"
        ],
        "city": "Meridian",
        "state": "ID",
        "postal_code": "83646",
        "country_code": "US",
        "phone": null,
        "fax": null,
        "email": null,
        "url": "https://www.markmonitor.com/contact-us/",
        "abuse_email": "abusecomplaints@markmonitor.com",
        "abuse_phone": "+1.2086851750"
      },
      "registrant": {
        "id": null,
        "name": null,
        "org": "Google LLC",
        "address": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country_code": "US",
        "phone": null,
        "fax": null,
        "email": null,
        "url": "https://domains.markmonitor.com/whois/contact/google.com"
      },
      "admin": null,
      "tech": null,
      "billing": null
    }
  ]
}

DNS.Tools API

Authentication

Free Tier (No API Key)

API Key Authentication

Example Authenticated Requests

Making Requests

Response Format

Rate Limits

Errors

HTTP Status Codes

OK

Bad Request

Unauthorized

Too Many Requests

Internal Server Error

DNS Lookup API

Domain Lookup API