Docs menu

Responses

Every tool returns the same envelope, so one parser handles them all. Only data differs from tool to tool; each tool's page in the tool reference lists its fields.

{
  "tool": "dns-lookup",
  "target": "example.com",
  "status": "ok",
  "fetched_at": "2026-11-14T10:00:00Z",
  "cached": false,
  "credits_used": 1,
  "credits_remaining": 498,
  "summary": "example.com resolves to 2 IPv4 addresses and receives mail through 1 MX host.",
  "score": null,
  "findings": [
    {
      "id": "dns.dnssec_unsigned",
      "severity": "info",
      "title": "Your domain isn't signed with DNSSEC",
      "detail": "...",
      "fix": "..."
    }
  ],
  "data": {}
}

Fields

FieldWhat it holds
toolThe tool's id.
targetWhat was checked, normalized: lowercase, with Unicode names in their ASCII form.
statusok, or partial when some sources didn't answer. A partial result says what is missing.
fetched_atWhen the data was fetched from its sources (UTC).
cachedWhether this answer came from our cache. It costs the same either way.
credits_usedWhat this call cost.
credits_remainingYour balance after the call. It can be below zero after a refund.
summaryOne plain sentence about the result.
score0 to 100 for tools that grade, otherwise null.
findingsProblems and notes, worst first.
dataThe tool's own result.

Findings

Each finding has a stable id you can switch on, a severity of fail, warn, info or pass, a short title, the detail for this target and a fix in plain words. Many findings link to a step-by-step fix guide on the website.

Fresh answers and caching

Most results are cached for a short time, so a repeat costs the same but answers at once. DNS answers follow the record's TTL. Add fresh=true to skip the cache when you need a new answer, for example right after changing a record. Fresh calls have their own rate limit.

Request ids and safe retries

Every response carries an X-Request-Id header. You can send your own (a UUID) with a call: if the network drops and you retry with the same id within 24 hours, you get the stored result, marked X-Replayed: true, and you aren't charged twice. Reusing an id for a different call returns 400 invalid_request.

Errors

A failure never uses this envelope. It returns an HTTP error status and one small body:

{ "error": { "code": "invalid_domain", "message": "...", "request_id": "..." } }

Errors lists every code and what to do about it.