DNS Lookup

POST https://api.echovalue.dev/dns-lookup

Runs DNS lookup and enrichment through echoValue.

The request is authenticated with x-token, charged by echoValue, and logged.

Request

Headers:

Header	Description
`x-token`	Your API token
`content-type`	Must be `application/json`

Body:

Field	Type	Required	Description
`domains`	string[]	Yes	Domain names or IP addresses to inspect
`recordTypes`	string[]	No	DNS record types to query: `A`, `AAAA`, `MX`, `CNAME`, `TXT`, `NS`, `PTR`, `SOA`, `CAA`, `SRV`
`checkPropagation`	boolean	No	Query multiple public resolvers to compare propagation
`propagationServers`	string[]	No	Override the resolver list used for propagation checks
`performReverseLookup`	boolean	No	Run PTR lookups for returned IPs or direct IP input
`enableEnrichment`	boolean	No	Enable SPF, DMARC, DKIM, provider, and security analysis
`enableSslInspection`	boolean	No	Inspect live TLS certificate metadata for HTTPS targets
`timeout`	integer	No	Per-query timeout in milliseconds. Min: `1000`. Max: `60000`. Default: `5000`
`maxRetries`	integer	No	Retry attempts for failed lookups. Min: `0`. Max: `10`. Default: `3`
`retryDelay`	integer	No	Delay between retries in milliseconds. Min: `0`. Max: `100000`. Default: `1000`
`includeMetadata`	boolean	No	Include additional lookup metadata

The service supports record types A, AAAA, MX, CNAME, TXT, NS, PTR, SOA, CAA, and SRV.

Examples:

curl 'https://api.echovalue.dev/dns-lookup' \
  -H 'x-token: mytoken' \
  -H 'Content-Type: application/json' \
  -d '{
    "domains": ["example.com"],
    "recordTypes": ["A", "MX", "TXT"],
    "checkPropagation": true,
    "performReverseLookup": true,
    "enableEnrichment": true,
    "enableSslInspection": true
  }'

Response

200 OK returns the DNS lookup result as JSON.

{
  "summary": {
    "totalDomains": 1,
    "successfulLookups": 1,
    "failedLookups": 0,
    "recordTypes": ["A", "MX", "TXT"],
    "propagationCheckEnabled": false
  },
  "results": [
    {
      "domain": "example.com",
      "lookupResult": {
        "domain": "example.com",
        "timestamp": "2026-04-22T09:15:00.000Z",
        "records": {
          "A": [
            {
              "type": "A",
              "address": "93.184.216.34",
              "ttl": 3600
            }
          ],
          "MX": [
            {
              "type": "MX",
              "exchange": ".",
              "priority": 0
            }
          ],
          "TXT": [
            {
              "type": "TXT",
              "entries": ["v=spf1 -all"],
              "ttl": 1800
            }
          ]
        },
        "spf_valid": true,
        "spf_strict": true,
        "dmarc_policy": "reject",
        "has_dkim": false,
        "email_security_score": 85,
        "ssl_certificate_expires_at": "2026-07-20T12:00:00.000Z",
        "ssl_days_until_expiry": 89,
        "warnings": ["No DKIM records detected"],
        "recommendations": ["Configure DKIM signing for email authentication"],
        "metadata": {
          "queryTime": 124,
          "totalRecords": 3
        }
      }
    }
  ]
}

Top-level fields:

Field	Type	Description
`summary`	object	Aggregate information about the whole request
`results`	array	One item per requested domain or IP address

summary fields:

Field	Type	Description
`totalDomains`	integer	Number of requested domains or IPs
`successfulLookups`	integer	Number of successful lookups
`failedLookups`	integer	Number of failed lookups
`recordTypes`	string[]	Record types requested for this run
`propagationCheckEnabled`	boolean	Whether propagation checks were enabled

results[] fields:

Field	Type	Description
`domain`	string	Requested domain or IP address
`lookupResult`	object	Main DNS lookup result for that target
`propagationResults`	array	Present only when `checkPropagation: true`

Common lookupResult fields:

Field	Type	Description
`domain`	string	Resolved target
`timestamp`	string (ISO 8601)	When the lookup completed
`records`	object	DNS records grouped by type
`reverseLookup`	object	PTR lookup result when reverse lookup is enabled and relevant
`mx_provider`	string or null	Best-effort provider inferred from MX records
`spf_valid`	boolean	Whether SPF parsing found a valid record
`spf_strict`	boolean	Whether the SPF policy is strict
`dmarc_policy`	string	DMARC policy when detected
`has_dkim`	boolean	Whether DKIM records were detected
`email_security_score`	number	Best-effort enrichment score from 0 to 100
`warnings`	string[]	Warnings from SSL or email-security analysis
`recommendations`	string[]	Suggested follow-up actions
`metadata`	object	Request metadata such as query time and record count

Typed DNS records:

A and AAAA records include address and optional ttl
MX records include exchange, priority, and optional ttl
TXT records include entries[] and optional ttl
CNAME, NS, and PTR records include value and optional ttl
SOA, CAA, and SRV records expose their standard protocol-specific fields

The response is partially typed in the OpenAPI spec, but some nested enrichment data can vary by target and enabled options.

Response headers:

Header	Description
`x-balance`	Wallet balance after this call
`x-cost`	Credits consumed for this request

See Response Headers for details.

Status Codes

Status	Meaning
`200`	Lookup completed successfully
`400`	Invalid request body or validation error
`401`	Invalid token
`402`	Wallet has insufficient credits
`405`	Method not allowed
`500`	Internal service error
`502`	DNS lookup service unavailable
`503`	DNS lookup service unavailable

Notes

400 responses can still return a structured JSON body.
5xx service responses consume 0 credits.
The endpoint accepts both domain names and IP addresses.
Propagation checks and enrichment can take noticeably longer than a basic DNS query.
The interactive service at lookup.echovalue.dev exposes the same analysis features in a browser UI.