Create a Ping Monitor

Last modified on July 26, 2024

To create a new ping monitor, send a POST request to /monitors/ping with a JSON body containing the monitor configuration.

Request URL

POST https://api.alertsite.com/api/v3/monitors/ping

Authentication

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": "example.com",
  "name": "ping example.com"
}

If you want to ping an IP address rather than a domain name, use:

{
  "billing_plancode": "UBM - A/A",
  "hostname": "203.0.113.5",
  "ipv4": "203.0.113.5",
  "resolve_dns": false,
  "name": "IP ping"
}

Parameters that are not specified in the request body will take the values specified in AlertSite defaults and your account defaults. For example, if you do not specify locations for the monitor, it will use your account's default monitoring location.

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

{
  "alert_note": "Optional alert notes",
  "allow_internal_testing": true,
  "billing_plancode": "UBM - A/A",
  "enabled": true,
  "home_location": 10,
  "hostname": "example.com",
  "interval": 5,
  "ipv4": "203.0.113.5",  // IP is only used if resolve_dns = true
  "locations": [
    {"id": 10},
    {"id": 20}
  ],
  "mode": "Global Verify",
  "monitor_location_count": 1,
  "name": "ping example.com",
  "note": "Optional dashboard notes",
  "notify_on_error": true,
  "resolve_dns": true,
  "retry_on_failure": true,
  "rotate_locations": true,
  "timeout": 1,
  "traceroute_on_error": true
}

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 ping monitor for example.com:

cURL (Windows)

curl -X POST https://api.alertsite.com/api/v3/monitors/ping
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d "{\"billing_plancode\": \"UBM - A/A\", \"hostname\": \"example.com\", \"name\": \"ping example.com\"}"


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

cURL (Bash)

curl -X POST https://api.alertsite.com/api/v3/monitors/ping \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"billing_plancode": "UBM - A/A", "hostname": "example.com", "name": "ping example.com"}'

Python

import requests # Requests library http://docs.python-requests.org
import json

baseUrl = 'https://api.alertsite.com/api/v3'
username = '[email protected]'  # Replace with your AlertSite login email
password = 'pa55w0rd'          # Replace with your AlertSite password

monitor_params = {
  'billing_plancode': 'UBM - A/A',
  'name': 'ping example.com',
  'hostname': 'example.com'
}

# Login
payload = {'username': username, 'password': password}
r = requests.post(baseUrl+'/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 = requests.post(baseUrl+'/monitors/ping', data=json.dumps(monitor_params), headers=headers)
result = r.json()
if r.status_code == requests.codes.ok:
    monitor_id = result['id']
    print('Successfully created the monitor. ID:{}'.format(monitor_id))
else:
    print('Could not create a monitor. The following error(s) occurred:', *result['errors'], sep='\n')

See Also

Monitor Operations
Get Monitor by ID
Get Monitors
Edit Ping Monitor

Highlight search results