Create a DNS Monitor

Last modified on May 22, 2024

To create a new DNS monitor, send a POST request to /monitors/name-server with a JSON body containing the monitor configuration.

Request URL



The request must include the Authorization header containing a user’s access token:

Authorization: Bearer ACCESS_TOKEN

See Authentication for more information.

The authenticating user must have permissions to create monitors.

Request body

The request body is a JSON object containing the monitor configuration parameters (see Monitor Object). The minimum required fields are:

  • billing_plancode

  • hostname

  • name

  "billing_plancode": "UBM - A/A",
  "hostname": "",
  "name": "DNS Sample Monitor"

Here is an example with all supported fields (see Monitor Object for a description of these fields):

 "alert_note": "Optional alert note",
 "allow_internal_testing": true,
 "billing_plancode": "UBM - A/A",
 "custom_properties": [
      "id": 228,
      "name": "Environment",
      "value": "development",
      "value_id": 550
  "enabled": true,
  "has_active_performance_alerts": false,
  "has_performance_alerts": true,
  "has_sla": false,
  "home_location": 10,
  "hostname": "",
  "id": 123456,
  "interval": 5,
  "ipv4": "",
  "locations": [
      "id": 10,
      "name": "Fort Lauderdale (FL)",
      "region": 1
      "id": 20,
      "name": "Atalnta (GA)",
      "region": 1
  "mode": "Global Verify",
  "monitor_location_count": 1,
  "name": "DNS Sample Monitor",
  "name_to_resolve": "",
  "name_to_resolve_id": 0,
  "note": "Optional monitor note",
  "notify_on_error": true,
  "port": "",
  "resolve_dns": true,
  "retry_on_failure": true,
  "rotate_locations": true,
  "sla_id": null,
  "timeout": 30,
  "traceroute_on_error": true,
  "type": "name-server"

Response body

On success, the operation returns the ID of the created monitor.

  "id": "123456"

Error responses have a non-200 status code and contain the errors list, such as:

  "errors": [
      "code": 400,
      "message": "invalid_request - User authentication failed."

Try it out

Click here to test this operation in AlertSite’s interactive API console.

Code examples

This code creates a DNS monitor to query IP address and test the DNS lookup for the domain name:

cURL (Windows)

curl -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d "{\"billing_plancode\": \"UBM - A/A\", \"hostname\": \"\", \"name_to_resolve\": \"\, \"name\": \"DNS Sample Monitor\"}"

Note: New lines are added for readability.
The actual command should be one continuous line.

cURL (Bash)

curl -X POST \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"billing_plancode": "UBM - A/A", "hostname": "", "name_to_resolve": "", "name": "DNS Sample Monitor"}'


import requests # Requests library
import json

baseUrl = ''
username = '[email protected]'  # Replace with your AlertSite login email
password = 'pa55w0rd'          # Replace with your AlertSite password

monitor_params = {
  'billing_plancode': 'UBM - A/A',
  'name': 'DNS Sample Monitor',
  'hostname': '',
  'name_to_resolve': ''

# Login
payload = {'username': username, 'password': password}
r ='/access-tokens', data=json.dumps(payload), headers={'Content-Type': 'application/json'})
token = r.json()['access_token']

# Create the monitor
headers = {
  'Authorization': 'Bearer ' + token,
  'Content-Type': 'application/json'
r ='/monitors/name-server', data=json.dumps(monitor_params), headers=headers)
result = r.json()
if r.status_code ==
    monitor_id = result['id']
    print('Successfully created the monitor. ID:{}'.format(monitor_id))
    print('Could not create a monitor. The following error(s) occurred:', *result['errors'], sep='\n')

See Also

Monitor Operations
Edit a DNS Monitor
Monitor Object Data Fields

Highlight search results