> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uptimeio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# DNS Monitoring

> Check that your domain resolves to the records you expect

A DNS monitor resolves a domain and compares the answer with the values you expect. It catches DNS misconfiguration, failed propagation and unexpected record changes (including hijacking). It does not check whether the resolved addresses are reachable; pair it with an [HTTP](/monitors/http) or [Port](/monitors/port) monitor for that.

## When to use it

* Confirm a domain resolves to the right IP addresses
* Verify a DNS change has propagated
* Watch MX, TXT or NS records for unexpected changes
* Detect DNS server outages

## Create a DNS monitor

<Steps>
  <Step title="Enter the domain">
    Use a public hostname such as `example.com`. Private and internal names, IP addresses in private ranges, and UptimeIO's own domains are rejected with a `VALIDATION_ERROR`.
  </Step>

  <Step title="Add record checks">
    Add one or more record checks: a record type, the expected values and how to compare them.
  </Step>

  <Step title="Optionally choose a DNS server">
    Leave it empty to use the default resolvers, or enter a resolver IP address such as `8.8.8.8`.
  </Step>

  <Step title="Set interval and locations">
    The interval minimum depends on your plan (Free 300 seconds, Pro and Scale 60 seconds). DNS answers change slowly, so every 5 minutes is usually enough. Pro and Scale can choose probe locations; Free uses automatic selection.
  </Step>
</Steps>

### Settings

| Field (API) | Description | Default |
| - | - | - |
| `name` | Monitor name, up to 80 characters | Required |
| `type` | `DNS` | Required |
| `target` | Domain to resolve | Required |
| `interval_seconds` | Seconds between checks | Required |
| `monitoring_regions` | Probe locations; `[]` for automatic. Free must send `[]` | Required |
| `dns_config.record_entries` | 1 to 10 record checks (below) | Required |
| `dns_config.dns_server` | Resolver IP address. Must be a valid IP | default resolvers |
| `dns_config.resolution_timeout_ms` | Resolution timeout, 1 to 60,000 | `5000` |
| `domain_monitoring` | Domain expiry warnings. See [Domain expiry monitoring](/monitors/http#domain-expiry-monitoring) | off |

Each entry of `record_entries`:

| Field | Description |
| - | - |
| `id` | Your identifier for the entry (non-empty string) |
| `record_type` | `A`, `AAAA`, `CNAME`, `MX`, `TXT` or `NS` |
| `expected_values` | At least one expected value |
| `validation_mode` | `exact`, `contains` or `regex` |

### Validation modes

| Mode | The entry passes when |
| - | - |
| `exact` | **Every** expected value appears in the resolved values. |
| `contains` | **At least one** expected value appears in the resolved values. |
| `regex` | At least one resolved value matches one of the expected values, treated as a regular expression. |

The monitor succeeds only when **all** record entries pass. An entry also fails when no records of that type exist.

<Note>
  For `MX` records the comparison uses the mail server hostname only (for example `mail.example.com`), not the priority.
</Note>

### Example

```bash theme={null}
curl -X POST https://api.uptimeio.com/api/monitors \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example.com DNS",
    "type": "DNS",
    "target": "example.com",
    "interval_seconds": 300,
    "monitoring_regions": [],
    "dns_config": {
      "record_entries": [
        {
          "id": "a-records",
          "record_type": "A",
          "expected_values": ["93.184.216.34"],
          "validation_mode": "exact"
        },
        {
          "id": "mx",
          "record_type": "MX",
          "expected_values": ["mail.example.com"],
          "validation_mode": "contains"
        }
      ],
      "dns_server": "8.8.8.8"
    }
  }'
```

## Record types

| Type | Purpose | Example expected value |
| - | - | - |
| `A` | IPv4 address | `93.184.216.34` |
| `AAAA` | IPv6 address | `2606:2800:220:1:248:1893:25c8:1946` |
| `CNAME` | Alias | `target.example.net` |
| `MX` | Mail server | `mail.example.com` |
| `TXT` | Text records (SPF, verification) | `v=spf1 include:_spf.google.com ~all` |
| `NS` | Nameservers | `ns1.example.com` |

## DNS server choice

| `dns_server` | When to use |
| - | - |
| Empty | Normal resolution as your users would see it |
| A public resolver (`8.8.8.8`, `1.1.1.1`) | Consistent results independent of the probe's resolver |
| Your authoritative nameserver IP | See changes as soon as you make them |

## Incidents

When a record check fails, UptimeIO records a DNS failure (for example no records found, or a value mismatch). An incident opens only after several probe locations confirm the failure (see [Understanding incidents](/essentials/understanding-incidents)). Connect an email, Slack or webhook channel so unexpected record changes reach you quickly.

## Best practices

* Monitor the records that matter: the apex A/AAAA, `www`, MX and any critical subdomains.
* If you use GeoDNS, answers differ by location; use `contains` or `regex` rather than one fixed address.
* Before a planned change, lower the record's TTL a day ahead so the change propagates faster.

## Troubleshooting

<AccordionGroup>
  <Accordion title="No records / NXDOMAIN">
    The domain or record type does not exist. Check registration and nameserver configuration with `dig example.com`.
  </Accordion>

  <Accordion title="Unexpected values">
    The records changed, a CDN or load balancer returns different addresses, or (if unauthorized) the domain may have been tampered with. Query your authoritative nameserver directly: `dig @ns1.example.com example.com`.
  </Accordion>

  <Accordion title="Invalid DNS server">
    `dns_server` must be an IP address, not a hostname.
  </Accordion>

  <Accordion title="Timeouts">
    Raise `resolution_timeout_ms`, or try a different resolver in `dns_server`.
  </Accordion>

  <Accordion title="Results differ between locations">
    Propagation may be in progress, or the domain uses GeoDNS.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="HTTP Monitoring" icon="globe" href="/monitors/http">
    Monitor web services and APIs
  </Card>

  <Card title="Notifications" icon="bell" href="/notifications/overview">
    Configure alerts for DNS monitors
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.