# 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](/docs/tools) lists its fields.

```json
{
  "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

| Field | What it holds |
| --- | --- |
| `tool` | The tool's id. |
| `target` | What was checked, normalized: lowercase, with Unicode names in their ASCII form. |
| `status` | `ok`, or `partial` when some sources didn't answer. A partial result says what is missing. |
| `fetched_at` | When the data was fetched from its sources (UTC). |
| `cached` | Whether this answer came from our cache. It costs the same either way. |
| `credits_used` | What this call cost. |
| `credits_remaining` | Your balance after the call. It can be below zero after a refund. |
| `summary` | One plain sentence about the result. |
| `score` | 0 to 100 for tools that grade, otherwise `null`. |
| `findings` | Problems and notes, worst first. |
| `data` | The 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](/docs/rate-limits).

## 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:

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

[Errors](/docs/errors) lists every code and what to do about it.
