# DNS.Tools API Documentation

Source: https://dns.tools/docs

---

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

-   [OpenAPI Spec](/openapi.json)
-   [Swagger UI](/openapi.html)
-   [llms.txt](/llms.txt)


## 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](mailto:support@dns.tools) 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.


### 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-KEY`** _(header)_
  - Provide your API key in an HTTP request header.

- **`Authorization: Bearer YOUR-API-KEY`** _(header)_
  - Authenticate using standard Bearer token format.


### Query Parameter Authentication

- **`?key=YOUR-API-KEY`** _(querystring)_
  - 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

- **`tool`** _(string, required)_
  - The specific API tool to use for analysis. Not all tools are currently supported through the API.
  - **Examples:** `dns`, `domain`

- **`query`** _(string, required)_
  - 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.com`, `sub.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=A`, `server=8.8.8.8`, `dnssec=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](#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

- **`tool`** _(string)_
  - The API tool that was used to process the request.
  - **Examples:** `dns`, `domain`

- **`query`** _(string)_
  - The original query that was submitted to the API.
  - **Examples:** `google.com`, `sub.domain.com`, `билеты.сайт`, `192.168.72.1`

- **`requestId`** _(string)_
  - A unique identifier for this request, useful for debugging and support.
  - **Examples:** `a7f9c2d4-8e1b-4c3a-9f6e-2d8b5e7c1a9f`

- **`timestamp`** _(string)_
  - The timestamp when the request was processed, in ISO 8601 format.
  - **Examples:** `2025-01-15T10:30:00.000Z`

- **`elapsed`** _(number)_
  - The time taken to process the request in milliseconds.

- **`cached`** _(boolean)_
  - Whether the request was served from cache. By default we cache results for up to 24 hours.
  - **Examples:** `true`, `false`

- **`results`** _(array, nullable)_
  - An array containing the tool-specific data.
  - **Examples:** `[{...}]`

- **`errorCode`** _(number, nullable)_
  - An HTTP status code for the error, or null for successful requests.
  - **Examples:** `400`, `401`, `429`, `500`

- **`errorName`** _(string, nullable)_
  - Human-readable error name, or null for successful requests.
  - **Examples:** `Invalid Query`, `Unauthorized`, `Too Many Requests`

- **`errorMessage`** _(string, nullable)_
  - 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](mailto: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.


### DNS Query Parameters

- **`type`** _(string)_
  - The type of DNS record type to query, or ALL for all common record types.
  - **Default:** `ALL`
  - **Examples:** `ALL`, `SOA`, `NS`, `A`, `AAAA`, `CNAME`, `DNAME`, `MX`, `TXT`, `CAA`, `TLSA`, `DS`, `DNSKEY`, `RRSIG`, `NSEC`, `NSEC3`, `NSEC3PARAM`, `CDS`, `CDNSKEY`, `KEY`, `SIG`, `SRV`, `HTTPS`, `SVCB`, `CERT`, `HINFO`, `TSIG`, `OPENPGPKEY`, `RP`, `SSHFP`, `URI`, `NAPTR`, `LOC`, `PTR`

- **`server`** _(string)_
  - DNS server to use for queries, or authoritative for authoritative server queries.
  - **Default:** `authoritative`
  - **Examples:** `authoritative`, `1.1.1.1`, `8.8.8.8`

- **`recursive`** _(boolean)_
  - 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:** `true`
  - **Examples:** `true`, `false`

- **`dnssec`** _(boolean)_
  - Enable DNSSEC validation and return additional DNSSEC records. Some nameservers do not support this and will return errors.
  - **Default:** `false`
  - **Examples:** `true`, `false`

- **`transport`** _(string)_
  - The DNS transport protocol to use. TCP allows larger responses, UDP is faster.
  - **Default:** `tcp`
  - **Examples:** `tcp`, `udp`

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.

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
    }
  ]
}
```