API Documentation

The Global DNS Checker API allows you to programmatically check DNS propagation across our worldwide network of DNS servers. Use it to monitor DNS changes, verify configurations, or integrate DNS checking into your applications.

Base URL

Authentication

All API requests require authentication using an API key. You can create API keys in your account dashboard.

Include your API key in the X-API-Key header with every request:

Keep your API keys secure

Never expose your API keys in client-side code or public repositories. If a key is compromised, delete it immediately and create a new one.

Rate Limits

API requests are rate limited to ensure fair usage and service stability.

Limit Type Limit
Requests per minute 60
Requests per day 1,000

Rate limit information is included in response headers:

Header Description
X-RateLimit-Limit Maximum requests in the window this response describes
X-RateLimit-Remaining Remaining requests in that window
X-RateLimit-Reset Time when that window resets (ISO 8601)
Retry-After Seconds to wait before retrying. Sent on a 429 only

Endpoints

DNS Lookup

Perform a DNS lookup across multiple servers worldwide.

GET /api/v1/lookup

Query Parameters

Parameter Type Required Description
domain string Yes The domain name to look up (e.g., example.com)
type string No Record type: A, AAAA, CNAME, MX, NS, PTR, SOA, SRV, TXT, CAA. Default: A
servers string No Comma-separated list of specific server IPs to query

Example Request

curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/lookup?domain=google.com&type=A"

Example Response

{
  "domain": "google.com",
  "recordType": "A",
  "summary": {
    "total": 25,
    "resolved": 24,
    "failed": 1
  },
  "results": [
    {
      "server": {
        "name": "Google Public DNS",
        "ip": "8.8.8.8",
        "country": "US",
        "city": "Mountain View"
      },
      "success": true,
      "records": ["142.250.185.78"],
      "responseTime": 23
    },
    {
      "server": {
        "name": "Cloudflare DNS",
        "ip": "1.1.1.1",
        "country": "US",
        "city": "San Francisco"
      },
      "success": true,
      "records": ["142.250.185.78"],
      "responseTime": 18
    }
  ]
}

List Servers

Get a list of available DNS servers.

GET /api/v1/servers

Query Parameters

Parameter Type Required Description
country string No Filter by country code (e.g., US, DE, JP)
limit integer No Maximum number of servers to return. Default: 100

Example Request

curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/servers?country=US&limit=10"

Example Response

{
  "total": 10,
  "servers": [
    {
      "name": "Google Public DNS",
      "ip": "8.8.8.8",
      "country": "US",
      "city": "Mountain View",
      "lat": 37.386,
      "lon": -122.0838
    },
    {
      "name": "Cloudflare DNS",
      "ip": "1.1.1.1",
      "country": "US",
      "city": "San Francisco",
      "lat": 37.7749,
      "lon": -122.4194
    }
  ]
}

List Countries

Get a list of countries with available DNS servers.

GET /api/v1/servers/countries

Example Request

curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/servers/countries"

Example Response

{
  "total": 103,
  "countries": [
    { "code": "US", "servers": 45 },
    { "code": "DE", "servers": 23 },
    { "code": "GB", "servers": 18 },
    { "code": "JP", "servers": 15 }
  ]
}

Query History

Every lookup you make with your API key is recorded and can be read back. The history covers your own account only: lookups made with another API key, and lookups made by visitors on the website, are never returned.

GET /api/v1/history

Query Parameters

Parameter Type Required Description
domain string No Case-insensitive substring filter on the queried domain
limit integer No Records to return, 1 to 100. Default 50. Values outside the range are clamped.

Example Request

curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/history?domain=google.com&limit=2"

Example Response

{
  "total": 17,
  "limit": 2,
  "queries": [
    {
      "_id": "6650c1a2f4b8d3e9a1c20b47",
      "domain": "google.com",
      "recordType": "A",
      "resolvedCount": 42,
      "failedCount": 3,
      "queryDate": "2026-08-13T09:14:22.118Z",
      "source": "api"
    },
    {
      "_id": "6650b83df4b8d3e9a1c20a02",
      "domain": "google.com",
      "recordType": "MX",
      "resolvedCount": 45,
      "failedCount": 0,
      "queryDate": "2026-08-13T08:31:57.004Z",
      "source": "api"
    }
  ]
}

Use the _id from that list to read one query in full, including every DNS server's individual answer.

GET /api/v1/history/:id

Example Request

curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/history/6650c1a2f4b8d3e9a1c20b47"

Example Response

{
  "_id": "6650c1a2f4b8d3e9a1c20b47",
  "domain": "google.com",
  "recordType": "A",
  "resolvedCount": 42,
  "failedCount": 3,
  "queryDate": "2026-08-13T09:14:22.118Z",
  "source": "api",
  "measured": true,
  "results": [
    {
      "server": "8.8.8.8",
      "serverName": "Google Public DNS",
      "country": "US",
      "city": "Mountain View",
      "success": true,
      "records": ["142.250.185.78"],
      "responseTime": 24
    }
  ]
}

A query that belongs to another account answers 404, the same as one that does not exist.

Error Handling

The API uses standard HTTP status codes to indicate success or failure.

Status Code Description
200 Success
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error

Error Response Format

{
  "error": "Description of what went wrong"
}

Rate Limit Error

{
  "error": "Rate limit exceeded",
  "limit": 60,
  "reset": "2024-01-15T12:00:00.000Z"
}

Code Examples

JavaScript (Node.js)

const response = await fetch(
  '${baseUrl}/lookup?domain=example.com&type=A',
  {
    headers: {
      'X-API-Key': 'dns_your_api_key'
    }
  }
);

const data = await response.json();
console.log(`Resolved: ${data.summary.resolved}/${data.summary.total}`);

Python

import requests

response = requests.get(
    '${baseUrl}/lookup',
    params={'domain': 'example.com', 'type': 'A'},
    headers={'X-API-Key': 'dns_your_api_key'}
)

data = response.json()
print(f"Resolved: {data['summary']['resolved']}/{data['summary']['total']}")

PHP

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,
    '${baseUrl}/lookup?domain=example.com&type=A');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: dns_your_api_key'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);

echo "Resolved: {$data['summary']['resolved']}/{$data['summary']['total']}";

cURL

# Basic lookup
curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/lookup?domain=example.com"

# Lookup with specific record type
curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/lookup?domain=example.com&type=MX"

# Lookup using specific servers
curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/lookup?domain=example.com&servers=8.8.8.8,1.1.1.1"

Need help? Check out our blog for tutorials and guides.