# Create a DNS Monitor

Creating a DNS monitor with DNSRadar is straightforward. Monitors allow you to track specific DNS records and receive notifications when changes are detected.

This guide will walk you through creating monitors using the API.

## Basic Monitor Creation

To create a monitor, send a POST request to the `/monitors` endpoint with the DNS record details you want to monitor.

```
POST https://api.dnsradar.dev/monitors

domain: piedpiper.com
  record_type: A
  expected_value: ["1.2.3.4", "5.6.7.8"]
```

### Request Parameters

- `domain` (required): The domain name to monitor
- `subdomain` (optional): The subdomain to monitor. Omit for apex domain monitoring
- `record_type` (required): The type of DNS record (A, AAAA, CNAME, MX, TXT, NS, PTR)
- `expected_value` (required): The expected DNS value(s). Can be a string or array of strings
- `frequency` (optional): Check frequency in minutes. Default: 60. Options: 5, 10, 15, 30, 60, 120
- `is_exact_match` (optional): Whether to require exact value matching. Default: true
- `group` (optional): Group slug to organize monitors. Uses default group if not specified

## Monitoring with Subdomains

To monitor a specific subdomain, include the `subdomain` parameter in your request.

```
POST https://api.dnsradar.dev/monitors

domain: piedpiper.com
  subdomain: www
  record_type: CNAME
  expected_value: piedpiper.netlify.app
  frequency: 5
```

> ℹ️ **INFO:** The `subdomain` parameter should contain only the subdomain portion. For example, to monitor `www.piedpiper.com`, use `subdomain: "www"` and `domain: "piedpiper.com"`.

## Understanding Expected Values

The `expected_value` parameter accepts either a single string or an array of strings, depending on your monitoring needs.

### Single Value

For DNS records that should have one specific value:

```json
{
  "expected_value": "piedpiper.netlify.app"
}
```

### Multiple Values

For DNS records that may have multiple valid values (like A records with multiple IPs):

```json
{
  "expected_value": ["1.2.3.4", "5.6.7.8"]
}
```

## Grouping Monitors

Groups allow you to organize monitors and manage webhook notifications collectively. By default, monitors are added to your default group, but you can choose another group when creating a Monitor, by passing a "slug".

If you pass a slug that doesn't exists at DNSRadar, we'll create the group for you on the fly.

```
POST https://api.dnsradar.dev/monitors

domain: piedpiper.com
  record_type: A
  expected_value: ["1.2.3.4"]
  group: production-servers
```

> ℹ️ **INFO:** **Webhook Management**: Webhooks are linked to groups, not individual monitors. This design allows you to manage notifications for multiple monitors efficiently by updating the group's webhook configuration.

If the specified group doesn't exist, it will be created automatically.

## API Response

When a monitor is successfully created, the API returns the monitor object with additional system-generated fields:

```json
{
  "uuid": "mon_abc123",
  "created": "2026-01-06T12:34:56Z",
  "domain": "piedpiper.com",
  "subdomain": null,
  "record_type": "A",
  "expected_value": ["1.2.3.4", "5.6.7.8"],
  "current_value": null,
  "is_exact_match": true,
  "state": "UNSET",
  "incidence_count": 0,
  "last_checked": null,
  "is_active": true,
  "frequency": 60
}
```

### Response Fields

- **uuid**: Unique identifier for the monitor (prefixed with `mon_`)
- **created**: ISO 8601 timestamp of monitor creation
- **current_value**: Current DNS value (null until first check)
- **state**: Monitor state (`UNSET`, `VALID`, `INVALID`, `TIMEOUT`, `MISMATCH`, `NOT_FOUND`)
- **incidence_count**: Number of incidents/changes detected
- **last_checked**: ISO 8601 timestamp of last check
- **is_active**: Whether the monitor is actively checking

## Monitor States

Understanding monitor states helps you interpret monitoring results:

- `UNSET`: Monitor created but not yet checked
- `VALID`: DNS record matches expected value
- `MISMATCH`: DNS record doesn't match expected value
- `NOT_FOUND`: DNS record doesn't exist
- `TIMEOUT`: DNS query timed out
- `INVALID`: DNS query returned invalid data

## Flexible Matching with is_exact_match

The `is_exact_match` parameter controls how strictly DNSRadar validates DNS records. When set to `false`, additional behavior applies based on the record type:

```
POST https://api.dnsradar.dev/monitors

domain: piedpiper.com
  record_type: TXT
  expected_value: v=spf1 include:_spf.service.com
  is_exact_match: false
```

For detailed information about flexible matching:
- [Flexible SPF Record Matching](/docs/spf-flexible-matching)
- [Flexible DMARC Record Matching](/docs/dmarc-flexible-matching)
- [Flexible MX Record Matching](/docs/mx-flexible-matching)
- [Flexible A/AAAA Record Matching](/docs/a-aaaa-flexible-matching)

## Rate Limits

> ⚠️ **WARNING:** The `/monitors` endpoint is rate-limited to 250 requests per minute. For bulk operations, consider using the [bulk creation endpoint](/docs/bulk-create-monitors).

## Plan Limitations

> ℹ️ **INFO:** **Free Plan**: Limited to 50 monitors and 60-minute check frequency.

**Premium Plans**: Support up to unlimited monitors and down to a 5-minute check intervals.

## Next Steps

- [Create multiple monitors at once](/docs/bulk-create-monitors)
- [Configure webhooks for notifications](/docs/configure-webhooks)
- [Manage monitor groups](/docs/update-monitors-bulk)