> ## Documentation Index
> Fetch the complete documentation index at: https://checkly-422f444a-playwright-vs-cypress-2026.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# DnsMonitor Construct

> Learn how to configure DNS monitors with the Checkly CLI.

<Tip>
  Learn more about DNS Monitors in [the DNS monitor overview](/detect/uptime-monitoring/dns-monitors/overview).
</Tip>

Use DNS Monitors to verify that DNS records resolve correctly and to track lookup performance over time.

<Accordion title="Prerequisites">
  Before creating DNS Monitors, ensure you have:

  * An initialized Checkly CLI project
  * A domain or hostname you want to monitor
  * Basic understanding of DNS record types (A, AAAA, CNAME, MX, NS, TXT, SOA, HTTPS)

  For additional setup information, see [CLI overview](/cli/overview).
</Accordion>

<CodeGroup>
  ```ts Basic Example theme={null}
  import { Frequency, DnsAssertionBuilder, DnsMonitor } from "checkly/constructs"

  new DnsMonitor("dns-monitor", {
    name: "DNS A Record Monitor",
    description: "Asserts `example.com` A record resolves to the **expected IP**.",
    activated: true,
    maxResponseTime: 1000,
    degradedResponseTime: 500,
    frequency: Frequency.EVERY_5M,
    locations: ["us-east-1", "eu-central-1"],
    request: {
      query: "example.com",
      recordType: "A",
      assertions: [
        DnsAssertionBuilder.jsonAnswer("$.Answer[0].data").equals("93.184.216.34")
      ],
    },
  })
  ```

  ```ts Advanced Example theme={null}
  import { Frequency, DnsAssertionBuilder, DnsMonitor } from "checkly/constructs"

  new DnsMonitor("advanced-dns-monitor", {
    name: "Advanced DNS Monitor",
    description: "Asserts `api.example.com` A record resolves to the **expected IP**.",
    activated: true,
    frequency: Frequency.EVERY_5M,
    locations: ["us-east-1", "eu-central-1"],
    maxResponseTime: 800,
    degradedResponseTime: 400,
    tags: ["dns", "production", "critical"],
    request: {
      query: "api.example.com",
      recordType: "A",
      nameServer: "9.9.9.9",
      port: 53,
      protocol: "UDP",
      assertions: [
        DnsAssertionBuilder.jsonAnswer("$.Answer[0].TTL").greaterThan(300),
        DnsAssertionBuilder.responseTime().lessThan(500),
        DnsAssertionBuilder.jsonAnswer("$.Answer[0].data").equals("93.184.216.34")
      ],
    },
  })
  ```
</CodeGroup>

## Configuration

A DNS Monitor has its own DNS-specific settings, plus the standard monitor options shared across all check types.

<Tabs>
  <Tab title="DNS Monitor Settings">
    | Parameter | Type | Required | Default | Description |
    | - | - | - | - | - |
    | `request` | `object` | ✅ | - | DNS request configuration object |
    | `degradedResponseTime` | `number` | ❌ | `500` | Response time threshold in milliseconds for degraded status |
    | `maxResponseTime` | `number` | ❌ | `1000` | Maximum response time in milliseconds before marking as failed |
  </Tab>

  <Tab title="General Monitor Settings">
    | Property | Type | Required | Default | Description |
    | - | - | - | - | - |
    | `name` | `string` | ✅ | - | Friendly name for your monitor |
    | `description` | `string` | ❌ | `null` | A description of the monitor. Supports markdown. Max 500 characters |
    | `activated` | `boolean` | ❌ | `true` | Whether the monitor is enabled |
    | `alertChannels` | `Array<AlertChannel \| AlertChannelRef>` | ❌ | `[]` | Array of AlertChannel objects for notifications |
    | `alertEscalationPolicy` | `AlertEscalationPolicy` | ❌ | - | Advanced alert escalation settings |
    | `frequency` | `Frequency` | ❌ | `EVERY_10M` | How often to run your monitor |
    | `group` | `CheckGroupV1` `CheckGroupV2` | ❌ | - | The CheckGroup this monitor belongs to |
    | `locations` | `string[]` | ❌ | `[]` | Array of public location codes |
    | `privateLocations` | `string[]` | ❌ | `[]` | Array of Private Location slugs |
    | `muted` | `boolean` | ❌ | `false` | Whether alert notifications are muted |
    | `tags` | `string[]` | ❌ | `[]` | Array of tags to organize monitors |
    | `testOnly` | `boolean` | ❌ | `false` | Only run with test, not during deploy |
    | `retryStrategy` | `RetryStrategy` | ❌ | - | Strategy for configuring retries |
    | `runParallel` | `boolean` | ❌ | `false` | Run monitors in parallel or round-robin |
    | `triggerIncident` | `IncidentTrigger` | ❌ | - | Create and resolve an incident based on the check's alert configuration |
  </Tab>
</Tabs>

### `DnsMonitor` Options

<ResponseField name="request" type="object" required>
  DNS request configuration that defines the DNS query to perform and how to validate the response.

  **Usage:**

  ```ts theme={null}
  new DnsMonitor("dns-monitor", {
    name: "DNS A Record Monitor",
    request: {
      query: "example.com",
      recordType: "A",
      assertions: [
        DnsAssertionBuilder.jsonAnswer("$.Answer[0].data").equals("93.184.216.34")
      ]
    }
  })
  ```

  **Parameters:**

  | Parameter | Type | Required | Default | Description |
  | - | - | - | - | - |
  | `query` | `string` | ✅ | - | The DNS query (domain name or IP address) |
  | `recordType` | `DnsRecordType` | ✅ | - | DNS record type: A, AAAA, CNAME, MX, NS, TXT, SOA, HTTPS |
  | `nameServer` | `string` | ❌ | - | Custom DNS server to query (e.g. "9.9.9.9") |
  | `port` | `number` | ❌ | `53` | Port of the DNS server |
  | `protocol` | `DnsProtocol` | ❌ | `UDP` | Protocol to use: UDP or TCP |
  | `assertions` | `DnsAssertion[]` | ❌ | `[]` | Response assertions using `DnsAssertionBuilder` |
</ResponseField>

<ResponseField name="degradedResponseTime" type="number" default="500">
  Response time threshold in milliseconds for marking the DNS Monitor as degraded (warning state).

  **Usage:**

  ```ts highlight={3} theme={null}
  new DnsMonitor("dns-performance-tiers", {
    name: "DNS Performance Tiers",
    degradedResponseTime: 300, // Warn at 300ms
    request: {
      query: "example.com",
      recordType: "A",
      assertions: [
        DnsAssertionBuilder.jsonAnswer("$.Answer[0].data").equals("93.184.216.34")
      ],
    },
  })
  ```
</ResponseField>

<ResponseField name="maxResponseTime" type="number" default="1000">
  Maximum response time in milliseconds before the DNS Monitor is marked as failed.

  **Usage:**

  ```ts highlight={3} theme={null}
  new DnsMonitor("fast-dns", {
    name: "Fast DNS Resolution",
    maxResponseTime: 500, // Fail at 500ms
    request: {
      query: "fast.example.com",
      recordType: "A",
    },
  })
  ```
</ResponseField>

### `DnsMonitor` Assertions

To define `assertions` for the `request` of an `DnsMonitor` you should use the `DnsAssertionBuilder`. The following sources are available for DNS monitor assertions:

* `responseTime()`: Assert the total response time of the DNS request in milliseconds. Use this to set thresholds for failed lookups
* `responseCode()`: By default, DNS monitors pass when the return code is NOERROR and fail on error codes (FORMERR, SERVFAIL, NXDOMAIN, etc.). You can override this behavior by defining a custom return code assertion
* `textAnswer()`: The raw DNS response as plain text. Use this to check for specific strings in the response
* `jsonAnswer(property?)`: The [DNS response in JSON format](/detect/uptime-monitoring/dns-monitors/configuration#json-response-schemas). This allows you to target specific fields using JSON path assertions. The response structure varies by record type. [Learn more about using JSON path](/detect/assertions/#json-responses-with-json-path).

Here are some examples:

* Assert the total response time of the DNS request

```ts theme={null}
DnsAssertionBuilder.responseTime().lessThan(1000)
// Equivalent to:
{ source: 'RESPONSE_TIME', comparison: 'LESS_THAN', target: '1000' }
```

* Assert the DNS response code

```ts theme={null}
DnsAssertionBuilder.responseCode().equals('NOERROR')
// Equivalent to:
{ source: 'RESPONSE_CODE', comparison: 'EQUALS', target: 'NOERROR' }
```

* Assert against specific JSON fields in the response.

```ts theme={null}
DnsAssertionBuilder.jsonAnswer('$.Answer.length').equals(4)
// Equivalent to:
{ source: 'JSON_ANSWER', property: '$.Answer.length', comparison: 'EQUALS', target: '4' }
```

Learn more in our docs on [Assertions](/detect/assertions).

### General Monitor Options

<ResponseField name="name" type="string" required>
  Friendly name for your DNS Monitor that will be displayed in the Checkly dashboard and used in notifications.

  **Usage:**

  ```ts highlight={2} theme={null}
  new DnsMonitor("my-monitor", {
    name: "DNS Resolution Monitor",
    /* More options ... */
  })
  ```
</ResponseField>

<ResponseField name="frequency" type="Frequency">
  How often the DNS Monitor should run. Use the `Frequency` enum to set the check interval.

  **Usage:**

  ```ts highlight={2} theme={null}
  new DnsMonitor("my-monitor", {
    frequency: Frequency.EVERY_1M,
    /* More options ... */
  })
  ```

  **Available frequencies**: `EVERY_10S`, `EVERY_20S`, `EVERY_30S`, `EVERY_1M`, `EVERY_2M`, `EVERY_5M`, `EVERY_10M`, `EVERY_15M`, `EVERY_30M`, `EVERY_1H`, `EVERY_2H`, `EVERY_3H`, `EVERY_6H`, `EVERY_12H`, `EVERY_24H`
</ResponseField>

<ResponseField name="locations" type="string[]" default="[]">
  Array of [public location codes](/concepts/locations/#public-locations) where the DNS Monitor should run from. Multiple locations provide geographic coverage and help detect regional DNS issues.

  **Usage:**

  ```ts highlight={2} theme={null}
  new DnsMonitor("global-dns-monitor", {
    locations: ["us-east-1", "eu-central-1", "ap-southeast-1"]
  })
  ```
</ResponseField>

<ResponseField name="activated" type="boolean" default="true">
  Whether the DNS Monitor is enabled and will run according to its schedule.

  **Usage:**

  ```ts highlight={2} theme={null}
  new DnsMonitor("my-monitor", {
    activated: false // Disabled monitor
  })
  ```
</ResponseField>