DNS Monitors

List All DNS Monitors

Retrieves your team's DNS monitors, newest first.

This endpoint is paginated. See Pagination for how to page through the full list.

Required scope: dns-monitors:read

Query Parameters

• perPageinteger

  Results per page, 1-200 (default: 50)

• cursorstring

  Page to fetch, taken from a Link header

Create a DNS Monitor

Creates a domain monitor and runs discovery immediately: every supported record type is queried at the domain, and at every name a pasted zone file declares.

Everything the resolver answered with is imported and watched. There is no review step on an API call — the dashboard's exists because a human is standing there — so a script that wants something left alone turns it off through the records sub-resource afterwards. The one exception is a record the zone file declares that the resolver does not answer for: it is imported unwatched, for the reason given below.

A team may hold 20 DNS monitors. Past that the create is refused with a 400 limit-exceeded problem, before the monitor row is written and before a single query is sent — one domain monitor sweeps every supported type at every tracked name, so the ceiling is what keeps a team's checks inside the platform's per-invocation budget. Delete a monitor to make room.

The response is 201 Created.

Required scope: dns-monitors:write

Request Body

• namestringRequired

  Monitor name (1-255 characters)

• domainstringRequired

  The domain to cover (1-255 characters)

• zoneFilestring

  A BIND zone file, up to 262144 bytes. Read once, parsed, and never stored.

• intervalSecondsinteger

  Check interval in seconds (900-86400, default: 86400)

• isEnabledboolean

  Whether the monitor is checked on its interval (default: true)

• registrationWarningDaysinteger

  Days before the domain registration expires to start alerting (1-365, default: 30)

The parser reads standard RFC 1035 zone-file syntax: <owner> [<ttl>] [IN] <TYPE> <rdata> records, ; comments, absolute and relative names, @ for the apex, $ORIGIN and $TTL, parenthesised multi-line records, owner-inheriting continuation lines, and quoted TXT character-strings. Anything it cannot use — $INCLUDE, $GENERATE, non-IN classes, untracked types, names outside the domain — is reported, never silently dropped, in discovery.rejectedLines, with the line the entry starts on.

A record the zone file declares but the resolver does not answer is imported unwatched, with status missing. That is a real finding at import — a stale delegation, a change that never published — and a poor standing alert, since the file is a snapshot that only gets older. Enable it through the records sub-resource if you want it watched. On a proxied zone this is the common case rather than the exceptional one: a proxied record is not in public DNS at all.

discovery.queriesFailed counts queries that did not answer. Those names are not covered by this import and no record is inferred from them; the monitor's next scheduled check tries again.

Get a DNS Monitor

Retrieves a single DNS monitor by ID.

Required scope: dns-monitors:read

Update a DNS Monitor

Updates a DNS monitor with a JSON merge patch: send only the fields you want to change.

There is no zoneFile here, and one sent is ignored rather than refused. The pasted text is never stored, so re-importing is a deliberate act rather than something carried along by a rename — import again from the dashboard, or create a new monitor.

Required scope: dns-monitors:write

Request Body

• namestring

  Monitor name (1-255 characters)

• domainstring

  The domain this monitor covers (1-255 characters)

• intervalSecondsinteger

  Check interval in seconds (900-86400)

• isEnabledboolean

  Whether the monitor is checked on its interval

• registrationWarningDaysinteger

  Days before the domain registration expires to start alerting (1-365)

The limits are the ones Create a DNS Monitor applies. null resets intervalSeconds to 86400, isEnabled to true and registrationWarningDays to 30; name and domain cannot be removed, so null on either is a 400 validation-error.

A new registrationWarningDays makes the registration due for a lookup on the next hourly sweep, so registrationStatus reflects the new window within the hour.

Changing domain does not re-run discovery: the records already tracked stay as they are, so point a monitor at a different domain only if you also mean to review its records.

Update With PUT

PUT /api/v1/dns-monitors/:dnsMonitorId takes the same fields, for integrations written before PATCH existed. A field you leave out keeps its value, null is refused, and sending isEnabled schedules the next check again on every request, even when the value is unchanged.

Required scope: dns-monitors:write

Delete a DNS Monitor

Permanently deletes a DNS monitor, every record it tracks, and its check history.

Required scope: dns-monitors:delete

Get DNS Monitor Results

Retrieves the check history for a DNS monitor: one row per check of the monitor, whatever the sweep cost in queries.

Results arrive newest first, a page at a time. See Pagination for how to walk the whole history.

Required scope: dns-monitors:read

Query Parameters

• perPageinteger

  Results per page, 1-200 (default: 50)

• cursorstring

  Page to fetch, taken from a Link header

responseTimeMs is the slowest single query in the sweep, not the sum: it answers "how long did DNS take to answer", which is a latency figure rather than a cost one.

A value edited inside a record set holding several values reads as one missing record plus one new one. That is truthful rather than a bug: DNS gives an individual record no identity of its own, so editing one value is indistinguishable, on the wire, from removing one and adding another. recordsChanged counts only the case a diff can attribute without guessing — a name and type holding exactly one watched record and answering with exactly one differing value.

List DNS Monitor Records

Retrieves every record the monitor tracks, including the ones you have declined to watch. The table is the complete set of everything ever seen for the domain: isEnabled says only whether a deviation from that record alerts, so a declined record stays listed rather than being rediscovered as new on the next check.

Required scope: dns-monitors:read

Records read alphabetically by name, then by recordType, then by value — the order you review a zone in — and arrive a page at a time. See Pagination for how to walk the whole table.

Query Parameters

• perPageinteger

  Results per page, 1-200 (default: 50)

• cursorstring

  Page to fetch, taken from a Link header

Field Meanings

• namestring

  Absolute owner name, lowercased, no trailing dot. The apex is the monitor's domain.

• recordTypeA` `AAAA` `CNAME` `MX` `TXT` `NS` `CAA` `TLSA` `DS` `SVCB

  The ten types checked.

• valuestring

  Normalized RDATA. Together with name and recordType it is the record's identity, and it is never client-writable.

• sourceresolver` `zone_file

  How the record first entered the table.

• isEnabledboolean

  Whether a deviation from this record alerts. The only writable field.

• statusok` `changed` `missing` `new` `error

  What the last check found. new and missing are states of the record, not of a check.

• lastSeenAtinteger | null

  Last check at which this exact record resolved. null for a zone-file record that has never resolved.

• lastCheckedAtinteger | null

  Last check that had an answer about this record. null until the first check.

Timestamps are epoch milliseconds.

Ownership

A monitor belonging to another team returns 404, not 403: a 403 would confirm the id names a real monitor somebody else owns.

Update a DNS Monitor Record

Enables or declines one record. This is how a script decides what a monitor watches: an API-created monitor imports and enables everything discovery found, because there is no reviewer standing at the other end of an API call.

Required scope: dns-monitors:write

Request Body

Send the body as application/merge-patch+json or application/json; both read the same.

{
	"isEnabled": false
}

Accepted Fields

• isEnabledbooleanRequired

  Whether a deviation from this record should alert

isEnabled is the only accepted field, and the request is rejected rather than filtered. Sending name, recordType, value, status, or any other key returns a 400 validation-error problem with a message naming the key — for example value: Unknown key.

A record's identity is (name, recordType, value), and it comes from DNS or from the zone file you imported, never from a client. It is also the key the check diffs on, so accepting an edit to it would silently retarget the expectation instead of changing it — and a request that was quietly ignored is worse than one that was refused, because the caller goes on believing the edit landed. Change your DNS, or re-import your zone file.

Omitting isEnabled, or sending it as null, is also a 400: a request with nothing writable in it expresses no decision, and answering 200 would claim one was made.

Enabling a record whose status is new also settles it to ok: it resolved when we found it, and you have now said you want it watched, so leaving it new would keep it on the "needs your attention" list forever. Every other status survives — enabling a zone-file record that has never resolved leaves it missing, which is true and is presumably why you enabled it. Declining a record never changes its status.

Ownership

A record id belonging to a different monitor — including one on your own team — returns 404. Records are addressable only through the monitor that tracks them.