DNS API Data Freshness: A Buyer's Cache Evaluation Test

Separate four clocks before comparing vendors

Write down which timestamp each field represents. A timestamp attached by your worker cannot establish when an upstream source changed.

Keep these times separate in stored reports. If observation time is unavailable, record that absence explicitly. Renaming the retrieval timestamp to “last verified” creates a stronger claim than the evidence supports.

DNS TTL adds another distinction. It governs cache behavior for a record; it is not a promise that every client has converged. The DNS specification defines record TTL semantics. Resolver policy, previous answers, and intermediary caches can affect what a caller sees. API cache controls therefore need their own test.

Read refresh semantics, not just product labels

Current vendor documentation illustrates why “fresh” needs a precise definition. WhoisXML API's request reference exposes cache-age and refresh controls with different retrieval behavior. Those controls belong to its registration product; they should not be assumed to describe its DNS products or another provider.

IPinfo's update guidance distinguishes dataset refresh schedules. A newly downloaded file is not automatically a newly built dataset. SecurityTrails documents historical DNS requests, where the observation period is part of the research question. Historical evidence can be useful while being unsuitable as a release gate's current answer.

HackerTarget's API documentation lists resolution and discovery operations separately. Before comparing prices, identify the exact operation, output format, and evidence type your workflow needs. A broader product menu does not settle cache behavior.

These are reasons to ask better procurement questions, not a freshness ranking. We have not run an authenticated cross-vendor benchmark. Use the following experiment on assets you control and retain the observations that support your own decision.

Set acceptance criteria for the decision you will make

Give each workflow an owner and an evidence budget. The owner decides how old a result may be, what uncertainty is acceptable, and what happens when the check cannot finish.

Avoid one universal freshness threshold. An overnight portfolio review and a cutover check have different consequences. Choose thresholds before seeing results so the evaluation does not become an exercise in explaining away failures.

For broader commercial questions, use the existing domain data buying framework. This test addresses one purchase condition in depth: whether a cache policy and its observable behavior fit your work.

Run a controlled DNS freshness experiment

1. Prepare an isolated marker

Create a dedicated TXT record in a test zone you control. Give it a unique marker and record its configured TTL. Keep it separate from production verification, mail, and service-discovery records. Choose a sampling interval and a hard request budget before starting.

2. Establish the baseline

Read the marker through the normal API path and store the complete response. Separately verify the authoritative value using your DNS provider's tools or authoritative queries. Record how you verified it. A console submission time alone is insufficient evidence that the change was published.

3. Change one variable

Update only the marker. Capture the time at which the authoritative source confirms the replacement. Keep the hostname, record type, caller location, and request settings stable. Mixing several changes makes disagreement harder to explain.

4. Compare documented request modes

Collect ordinary and cache-bypass requests at your chosen cadence. Treat them as paired observations, not independent resolver populations. A bypass request might refresh a cache subsequently used by the ordinary request; ask the provider about that behavior.

5. Record outcomes without manufacturing certainty

Classify each sample as matching, different, or unknown. Preserve HTTP errors, timeouts, unsuccessful response envelopes, and unexpected record shapes. Stop at the budget limit. The first matching sample gives a run-specific observation time, with uncertainty between samples; it is not a platform-wide freshness guarantee.

Repeat with separate markers if you need isolated comparisons. Retain ordinary-path failures as well as bypass successes. Buying only against the successful samples hides the behavior that on-call teams will eventually have to handle.

Collect evidence with the documented API

Ops.Tools documents address, type, skipCache, and cacheTimeSeconds for DNS record lookup. The public request contract describes cache bypass, but does not promise that it bypasses every downstream recursive cache or queries a chosen authoritative server.

Use an API key from your server-side secret store. Set CHECK_HOST to your controlled test hostname. This is a real request shape; the marker and experiment setup are yours.

curl --fail-with-body --silent --show-error --max-time 20 \
  --get 'https://api.ops.tools/v1-dns-lookup' \
  --header "x-api-key: ${OPS_TOOLS_API_KEY}" \
  --data-urlencode "address=${CHECK_HOST}" \
  --data-urlencode 'type=TXT' \
  --data-urlencode 'skipCache=true'

The following JavaScript collector runs in a Node.js environment with built-in fetch. Save it as collect-freshness.mjs. It makes two sequential calls and writes JSON Lines to standard output. Run it at the cadence you selected and store the output as an artifact.

const apiKey = process.env.OPS_TOOLS_API_KEY;
const address = process.env.CHECK_HOST;
if (!apiKey || !address) throw new Error('Set OPS_TOOLS_API_KEY and CHECK_HOST');

for (const skipCache of [false, true]) {
  const url = new URL('https://api.ops.tools/v1-dns-lookup');
  url.search = new URLSearchParams({
    address,
    type: 'TXT',
    skipCache: String(skipCache),
  }).toString();
  const requestedAt = new Date().toISOString();
  const started = performance.now();
  try {
    const response = await fetch(url, {
      headers: { 'x-api-key': apiKey },
      signal: AbortSignal.timeout(20_000),
    });
    const body = await response.text();
    console.log(JSON.stringify({
      requestedAt,
      receivedAt: new Date().toISOString(),
      elapsedMs: Math.round(performance.now() - started),
      skipCache,
      status: response.status,
      body,
    }));
    if (!response.ok) process.exitCode = 1;
  } catch {
    console.log(JSON.stringify({ requestedAt, skipCache, outcome: 'unknown' }));
    process.exitCode = 1;
  }
}

The recorded body remains evidence, not an automatic pass. Validate success, the returned address and type, and the record shape before interpreting a marker. The spec leaves records structurally open, so a TXT parser must be checked against actual responses before it controls a release.

For comparison, this A-record object is the documentation's example, not a live observation or a promised address for example.com:

{
  "success": true,
  "address": "example.com",
  "type": "A",
  "records": ["93.184.216.34"]
}

Apply the same discipline beyond DNS

For registration checks, the documented bypass parameter is noCache, and parsed fields require parseWhoisToJson=true. Do not copy the DNS parameter name. The parsed object is optional and does not guarantee a uniform expiration field across registries. Preserve raw registration text and reconcile renewal decisions with the registrar account.

For IP location and network context, keep country, ASN, and organization fields separate from asset ownership. A network operator's identity does not identify every customer using its addresses. Cache bypass cannot make an upstream dataset more recent than its own publication.

For certificate validation, compare validity dates, remaining days, and the observed certificate identity. A recently retrieved certificate can still be the wrong certificate for a planned rollout. Validate the expected hostname and deployment context, and repeat the check while an old redirect remains in service.

When combining these results, give each its own retrieval time and outcome. A domain report assembled today can contain sources observed at different times. That matters for security triage, portfolio decisions, and the service retirement workflow.

Price the usable result and write the acceptance terms

Count the calls needed to reach a usable decision, including repeated sampling and confirmation. An illustrative test with ten hostnames, two request modes, and six sampling rounds requires 120 requests before retries. This is arithmetic for a proposed experiment, not a throughput benchmark.

The Ops.Tools pricing page states one credit per API request. Professional plans starting at $6.99/month. Confirm how your purchased terms handle failures, cache modes, limits, and repeated requests before extrapolating costs. The usage cost model helps turn the experiment into a workload forecast.

For bulk audits, use a bounded worker and record progress per asset. Separate routine inventory refreshes from time-sensitive release checks so a large scheduled job does not consume the entire request budget. Store sufficient provenance to explain why a decision used a particular sample.

Finish procurement with a short acceptance record: workflow, required fields, allowed evidence age, sampling method, observed exceptions, retry ceiling, escalation owner, and purchase conditions. Distinguish contractual commitments from your own test results. Availability, support response, and data freshness are separate promises; ask for each explicitly.

Questions buyers should settle

Does cache bypass prove global DNS propagation?

No. It requests the documented provider behavior. It does not establish what every recursive resolver or client sees. Pair the observation with authoritative evidence and the checks required by your deployment policy.

Can a retrieval timestamp replace a missing observation timestamp?

No. Store it as retrieval time and mark source age unknown. Decide whether that uncertainty is acceptable for this workflow before production adoption.

Should every request bypass caches?

Choose by purpose. Routine inventory jobs and urgent release decisions may need different policies. Measure the request cost and behavior of both modes, then document the choice rather than assuming bypass is always better.

Start with a controlled marker, the documented request contract, and a decision your team actually needs to make. Use the results to choose a plan and acceptance terms that you can explain to procurement and the next engineer on call.