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

Reverse Lookup

Resolve an IP address to its hostnames (PTR) across the same worldwide resolver pool as a forward lookup.

GET /api/v1/reverse

Query Parameters

Parameter Type Required Description
ip string Yes The IPv4 or IPv6 address to reverse-resolve

Example Request

curl -H "X-API-Key: dns_your_api_key" \
  "${baseUrl}/reverse?ip=8.8.8.8"

Example Response

{
  "ip": "8.8.8.8",
  "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,
      "hostnames": ["dns.google"],
      "responseTime": 24,
      "error": null
    }
  ]
}

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.

GraphQL API

The same DNS data is available over GraphQL at a single endpoint. This endpoint is public and needs no API key, but it shares the per-IP rate limit of the other public endpoints rather than the API-key quota above.

POST /graphql

Root Fields

Field Arguments Returns Description
lookup domain: String!, type: String LookupResult! Forward DNS lookup across the worldwide pool. Type defaults to A. Supported types: A, AAAA, CNAME, MX, NS, PTR, SOA, SRV, TXT, CAA
reverse ip: String! ReverseLookup! Reverse (PTR) lookup for an IPv4 or IPv6 address across the same pool
servers country: String, limit: Int [Server]! Active DNS servers, optionally filtered by country code
server ip: String! Server A single server by its IP address
countries none [Country]! Countries with active servers and their server counts
stats none Stats! Total server, country and query counts
Query limits

Each operation is capped: query depth at most 5, at most 5 root fields, and lookup and reverse together at most once per operation, since both fan out across the whole resolver pool. A query that exceeds a limit answers 400 with the code QUERY_TOO_COMPLEX. Schema introspection is disabled in production.

Example Request

curl -X POST "${graphqlUrl}" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ lookup(domain:\"example.com\", type:\"A\") { domain recordType resolved failed results { server { ip country } success records responseTime } } }"}'

Example Response

{
  "data": {
    "lookup": {
      "domain": "example.com",
      "recordType": "A",
      "resolved": 24,
      "failed": 1,
      "results": [
        {
          "server": { "ip": "8.8.8.8", "country": "US" },
          "success": true,
          "records": ["93.184.216.34"],
          "responseTime": 23
        }
      ]
    }
  }
}

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
503 Service Unavailable - Rate-limit store unreachable; retry after the Retry-After header

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.