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

We offer a generous free tier so you can start using the API immediately. With 1,000 requests per month, it's perfect for testing and light usage.

Create an account to get an API key and use the free tier — no credit card required.

GET

API Key Authentication

Every request must be authenticated with your API key. We support three methods of providing it:

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 API key. 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? See our pricing to upgrade your plan, or contact us for custom high-volume and enterprise solutions.

Credits & Billing

API usage is measured in credits. The rules are simple:

Every successful lookup costs one credit, including lookups that return a 404 not-found result.
Cached and live responses cost the same.
Failed requests on our side (5xx errors) don’t count.

The free tier includes 1,000 credits per calendar month (UTC), no card required. Paid plans include larger monthly allotments and bill anything over at the plan’s per-credit rate. See Pricing for the plans and rates.

Credit Headers

Every API response reports your live credit status in the response headers:

Credit Response Headers

X-Credits-Used: 812
X-Credits-Included: 1000
X-Credits-Remaining: 188
X-Credits-Reset: 2026-08-01T00:00:00.000Z

When Credits Run Out

When a monthly allotment is exhausted or a self-set spend ceiling is reached, requests return HTTP 402 with the standard error envelope. Active paid plans in good standing with a card on file aren’t interrupted at 100% — usage simply continues into pay-as-you-go overage.

402 Response Example

{
  "tool": "dns",
  "query": "example.com",
  "requestId": "b3e8f1a6-7c2d-4b9e-8f5a-3c6d9e4f2b8c",
  "timestamp": "2026-07-15T10:30:00.000Z",
  "elapsed": 2,
  "cached": false,
  "errorCode": 402,
  "errorName": "Payment Required",
  "errorMessage": "Monthly credit limit reached (1,000 free credits, resets 2026-08-01). Higher limits and overage: https://dns.tools/account/billing",
  "results": null
}

Watch X-Credits-Remaining as you approach your allotment — account holders also get an email at 80% and 100% of included credits.

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.
402
Payment Required
Monthly included credits are exhausted, or a self-set spend ceiling was reached. The errorMessage explains which — see Credits & Billing.
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

subdomainsboolean

Probe well-known subdomains (www, mail, _dmarc and many more) alongside the domain itself. Set to false to probe only a handful of the most common names, which is considerably faster. Applies to ALL, A, AAAA, CNAME and TXT queries for a base domain — other record types, and queries for a subdomain, are unaffected.

Default:trueExamples: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: {
    // required — set your API key
    '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: {
    // required — set your API key
    '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,
      "epp_status": [
        "clientUpdateProhibited",
        "clientTransferProhibited",
        "clientDeleteProhibited",
        "serverUpdateProhibited",
        "serverTransferProhibited",
        "serverDeleteProhibited"
      ],
      "availability": "registered",
      "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

API Key Authentication

Example Authenticated Requests

Making Requests

Response Format

Rate Limits

Credits & Billing

Credit Headers

When Credits Run Out

Errors

HTTP Status Codes

OK

Bad Request

Unauthorized

Payment Required

Too Many Requests

Internal Server Error

DNS Lookup API

Domain Lookup API