Skip to main content

WHOIS response data and quality

WHOIS data varies by registry, TLD, and source. Read the API reference for the exact published schema. Treat optional fields as optional even when they are present in examples.

Interpret registration first​

For a successful single lookup, inspect data.registration.registered. A conclusive registered or unregistered result is a successful lookup. An unknown or inconclusive outcome does not establish that a domain is unregistered or available to purchase.

For batch result pages, inspect each row's status, state, and optional error_code. HTTP success for the page means the page was returned; individual lookups can still fail or remain inconclusive.

Handle missing and redacted fields​

Registry policy and source availability can limit dates, registrar information, nameservers, and contact data. Do not assume that a missing optional field is an empty string or that it makes the domain unregistered.

Read data.quality.warnings on single results for missing or redacted data. Preserve the distinction between an absent value and a conclusive registration outcome. Avoid using free-form registry text or warning messages as stable application enums; use the structured fields documented in the reference.

Understand successful units​

WHOIS uses domains as its processing unit:

  • Both registered and conclusively unregistered outcomes count as successful lookups.
  • Repeated domains in one batch are normalized and processed once for billing. Result rows still preserve the original input positions.
  • Invalid input, unknown outcomes, upstream errors, timeouts, and unexecuted items are not billable items.
  • A cache hit can still be a successful lookup.
  • Cancellation stops new work. Items already completed successfully still count when the batch settles.

Starting another batch for the same domains is a new operation. Repeating the original submission with the same idempotency key recovers the existing operation.

Use settlement records for charges​

Do not calculate a charge from the number of response rows or from public result fields. Duplicate inputs and failed lookups make that count different from the final billable quantity. Use Console's final receipt and usage records.

See Credits and billing for reservations and settlement, batch lookups for job recovery, and errors and recovery for transient failures.