The NodePing API and PowerShell

At NodePing we interact with our own API quite a bit from the command line.  Most of that is from bash on Linux, because that’s where we live most of our lives.  But the API works well from just about any scripting environment.  Since our documentation examples all use curl with bash syntax, it seemed like it might be a good idea to also write up some examples of using other tools.  Here, as the first installment of that effort, is a handful of examples of using PowerShell with the NodePing API.

Full disclosure: PowerShell is not an environment we spend a lot of time working with.  There are likely ways to do some of this better.  We’ve tested the example calls in this post.  Hopefully it is enough to get you started if you work with PowerShell.

Basic GET Calls

Basic calls are quite simple to make using Invoke-RestMethod.  If you have the check ID, getting a check is quite easy:

Invoke-RestMethod ‘[token]’

This returns a JSON object, which PowerShell handles easily.

_id : 201205050153W2Q4C-0J2HSIRF
description : This is the description, if the check has one.
public : False
customer_id : 201205050153W2Q4C
queue : nyI8JSL23W
interval : 1
created : 1427513104608
pro :
modified : 1510332098196
parameters : @{target=; follow=False; threshold=5; sens=2; invert=False; verify=false}
firstdown : 0
label : Keep me
runlocations : False
enable : active
uuid : bd3eha9o-z2m5-4qg2-9k8b-jqq0kiituyxz
state : 1
status : assigned
notifications : {}
type : HTTP
acctdisable : False
suspacct : False
dep : False

Note that “parameters” is another hash.  You can refer to the fields in the check as properties of the returned object, including properties that are hashes themselves.  So, for example, this will give you the check check threshold, which is part of “parameters”.

$check = Invoke-RestMethod ‘[token]’ ;

API Authentication

PowerShell doesn’t easily support basic authentication.  Since the NodePing API supports passing the token as a parameter, the easiest approach is to include it in the query string, as I did in the example above.  In most cases I prefer to pass it in the Body, as I’ll show in examples below.  If you’re working with a script its usually easiest to set a $token variable and use that throughout your script.  If you’re just sending a URL as I did in the simple GET calls above, actually putting in the query string works fine.

If you’re using the API in scripts that make several calls to the API, you might want a more reusable way to pass the token that keeps it out of your Body.  You can do this by manually building the headers.  That requires base64 encoding the credentials and then setting that using the -Headers argument. That looks something like this:

$hash = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(("{0}:{1}" -f $token,"")))

Then set the -Header argument to @{Authorization=(“Basic {0}” -f $hash)}

Or, if you are doing this several times, you will probably want to set this to a variable you can reuse.

Some sites suggest that you create a credential object using ConvertTo-SecureString and Management.Automation.PSCredential, and pass that using the -Credential argument.  However, this won’t work with the NodePing API, since the -Credential option waits for the challenge to send the authorization header.  The API is stateless, and expects the header on each request.

Put and Post Calls

We recommend that you use JSON to set fields for our API in most environments.  However, PowerShell does not automatically handle sending the body as JSON.  For POST calls, this isn’t a big deal, and you can just POST the body as it is and Invoke-RestMethod sends the data as if it were a form.  PUT and DELETE calls don’t work that way.  For those, you have to convert to JSON, or include all of your parameters in a query string.

Creating a check looks like this:

Invoke-RestMethod '' -Method Post -Body @{ 
    label='test label' 

This call will return an object with the new check.  You can add any of the other fields listed in our documentation.

Updating a check is almost the same.  This can all be done on one line, but we’ll split it out here to make it easier to see.

$data = @{ label='a new label'; type="HTTP"; interval=5; token=$token } | ConvertTo-Json
Invoke-RestMethod '' -Method Put -Body $data

Note that since we’re updating a check, we need to include the check ID.  As with the Post call, the Put call returns the updated check object.

Working with Lists of Checks

Working with a list of checks is slightly trickier.  The call returns a JSON object with a list of checks using the ID as the key.  For PowerShell, this is a hash table of hashes.  So to list checks, you would do something like this:

Invoke-RestMethod '' -Body @{ token=$token } | %{ $_.PSOBJECT.Properties.value }

This is actually fairly handy, because you can fairly easily list a specific field from the response.  For example, this lists all of the targets from all of the checks on this account:

Invoke-RestMethod '' -Body @{ token=$token } | %{ $ }

You could do all sorts of things at this point.  For example, here’s a list of all checks that include “nodeping” somewhere in the check’s target:

Invoke-RestMethod '' -Method Get -Body @{ token=$token } | %{ foreach($value in $_.PSOBJECT.Properties.value){ if($ -like "*nodeping*"){ $value } } }

This is practical as a way to find a check with a specific target up to a few thousand checks.

Getting Results

Applying the same principles should let you do just about anything with the NodePing API.  Applying the same pattern to a results call, for example:

Invoke-RestMethod '' -Method Get -Body @{ token=$token; limit=2; clean=1 }

Note that you’ll want to always include the “clean” parameter for results.  The unclean response takes more parsing.

The options available for results calls are documented here:


That’s the basics of using PowerShell to interact with the NodePing API.  With the API you can add checks, remove checks, get your results and uptime, manage contacts and notifications, and add and manage subaccounts.  Our customers use the API both for programmed integrations, and from the command line using quick scripts like the ones I demonstrated here to make quick changes to several (or lots) of checks at once.

If you’re doing interesting things with PowerShell and the NodePing API, we’d like to hear about it!  Please email support and let us know.  That’s also a great place to ask us questions.  We’re happy to help people interact with our service.

Notification Escalations on NodePing

Most systems run smoothly most of the time.  Servers keep running.  Web sites serve pages and deliver data from backend databases.  DNS servers respond to queries with hardly any delay at all.  Email flows smoothly.

Emergency_light_with_grillIt’s that tiny percent of the time that it doesn’t work that way that causes the heartburn.  A server that has been running just fine for months suddenly hiccups.  But even when that happens, it’s usually a hiccup.  The person who is the first line of responsibility for that service needs to know right away.  They jump on it, clear the problem, and things go back to humming like normal.  You need fast and reliable monitoring to help keep these interruptions to service short.  A lot of times, the service is back to normal before most people realize there was an issue.  These incidents likely go in a report, but the rest of the team doesn’t need to get involved.  Its dealt with, duly noted, and life goes on.

Then there are the times that something goes really wrong.  The first line is working on it, but the server isn’t going to be back up in a minute or two.  Or the first line person is not available.  Maybe he’s in accounting trying to sort out his paperwork for credit card expenses for last month.  Someone else needs to know that things are down.

Sometimes these situations turn into real disasters.  The website is down.  Upper management is going to be calling, wondering who’s spilling revenue out on the server room floor.  The manager getting that call wants to know about it before the phone rings with that call.

Most monitoring systems use escalating notifications to handle these situations.  If a system is down, the first line person should be notified immediately.  If it’s down for a few minutes, the people who back him up need to be brought in.  If it’s down longer than that, systems management will want to get a heads up.

NodePing uses the notification delay feature to provide notification escalations.  A delay can be set on each notification contact for each check.  The NodePing notification delay feature notes that a check set with a delayed notification has gone down.  After the delay interval has been reached, if the check is still “down” we send the notification to that contact.

Set up the first line systems with no delay, so they’ll get notified when the system goes down right away.  If the service hasn’t recovered in a few minutes, send a notification to the systems group using a contact group.  Then, if the service hasn’t recovered in 10 minutes (or whatever the tolerance for the service being down is for this service in your organization), notify the systems management.

The notification delay feature can be used for other things besides notifications.  Sometimes services have a higher tolerance for transient interruptions.  You can use the delay to mean “if this service is down shorter than 3 minutes, I don’t need to be notified.”  This is useful, for example, for services in remote locations where Internet connectivity can have brief interruptions.  But our most common request for using the delays are for notification escalations.


Creating Clones

Have you ever wanted to be an evil genius and create a clone army to take over the universe? Well, we can’t help you with that but we do have a “Clone Check” feature. It might not take over the universe, but it can be a great time-saver.


When you want to create a check that is similar to one you already have, you can use our “Clone Check” feature to create a new check based on the settings of an existing check. You can then change whichever fields you choose, such as the URL or check type, as well as the label. This saves you from having to type in the various fields over and over or set complicated notifications, delays, etc, when you already have a similar check ripe for cloning.

To clone a check, log into your NodePing account, and go to the “Checks” tab. Click on the label for the check you want to duplicate to open the information drawer. On the lower right, there are a list of links, including “Clone Check”. Clicking on it will bring up a new dialog for the cloned check with all of the values preset based on the check you are cloning. You can change the fields to fit the new check you want. Then click “Save” at the bottom of the dialog.

Who knows? If you create enough, maybe you can take over the universe.

Notification Dependencies

Oh no! A power supply failure has taken your website server offline and here comes 120 HTTP ‘down’ notifications from NodePing. When a major outage hits, the last thing you need is an alert flood for all the checks you already know are bound to fail.

When a check depends on other services or networks, you don’t need more notifications that it’s failing when you already know the service that it depends on is failing. NodePing recently released a new feature called ‘Notification Dependency’ to help mitigate that unhelpful alert flood.

Set a ‘Notification Dependency’ on your checks when you want to suppress notifications for checks that depend on another check for availability. Web sites on the same web server can all be set to have their HTTP checks dependent on the server PING check. Or, you can set server PING checks to be dependent on the network router PORT check. If the dependent check is failing, no notifications will be sent for the check. The checks will still fail, only alerts won’t be sent for those failures.

Choose your dependent check from the ‘Dependency’ dropdown in the ‘Notifications’ section of the check edit modal and then ‘Save’ your changes for that check.

Notification dependencies are another way to help you receive only actionable alerts for your uptime monitoring and are available to all NodePing customers.

If you aren’t using NodePing server monitoring yet, sign up for your free, 15-day trial today.

Delayed Notifications

NodePing now offers delayed notifications for your uptime monitoring. This is a powerful new feature that will help make your notifications actionable. There are two primary use cases for delayed notifications: flapping services and escalating notifications.

Flapping Services
Not all services or networks are rock solid. Sometimes three or even two nines is “good enough”. Some locations have inherently lower expectations for availability or are just prone to frequent, short-lived outages. When a check often fails but recovers by itself quickly (flaps), it’s difficult to get actionable notifications.

Adjusting the check sensitivity setting down is useful to give your check more time to recover but if unassisted recovery takes longer than a minute the check will still likely fail. Use delayed notifications for flapping checks to receive alerts only when services are ‘really’ down. You can configure NodePing to send a alerts if your check remains down after say 5 minutes. Set the delay (from 1 minute to 1 hour) to your tolerance and receive only alerts when human intervention is required.

Escalating Notifications
Not everyone needs to know about every outage right away. If the sysadmin on call can get the site back up within a few minutes, there’s no action required by senior staff or for the help desk to be informed. If an outage lasts longer, however, you may need to let your boss know things are still offline or give a heads up to the help desk that there are issues on the website and to expect some calls. Use delayed notifications to set escalating alerts to others if an outage continues.

You can even escalate alerts to yourself. I have several checks set to email me immediately and then send me an SMS if they’re still failing after 5 minutes and a voice call if the outage lasts longer than 10 minutes.

Setting Notification Delays
When editing a check, you’ll see the contact method drop down in the ‘Notifications’ section of each check. Choose a contact method and the ‘Delay’ and ‘Schedule’ dropdowns will also appear. You can set different delays on the same contact method by adding additional lines with the same contact method.

Actionable Alerts
Delayed notifications can be useful to make all your alerts more actionable. If your contacts are ignoring NodePing notifications, they’ll succumb to alert fatigue and eventually ignore a truly important notification.

If you need any help tuning your checks to avoid flapping or adjusting your notifications to make them more actionable, please reach out to us at We really are happy to help.

If you aren’t using NodePing for uptime monitoring yet, please sign up for our 15-day, free trial and let us help you increase your uptime.

Disable Monitoring

Last week we added several features aimed at making our monitoring service easier to manage and use.  One of those features adds new ways to easily disable checks, either in the UI or using the API. Disabling a check stops all monitoring and notifications. It can be useful to keep scheduled maintenance or downtime from affecting your uptime statistics. I’ll explain a bit on the various ways you can disable monitoring within NodePing.

Disabling a Single Check
There are two ways to disable a single check within the NodePing web interface. The first is in the check details drawer. If you click the name of a check in the list, the details drawer will slide out. There you can see the last 5 results, links to the various reports, and a toggle to disable the check. Simply click on the “toggle” link next to the text “This check is currently active”. To re-enable, click the toggle again.

The second way to disable a single check is within the check edit screen. Click on the “Edit” button to call up the check edit modal and remove the checkbox from the “Enable Check:” field, then click on “Save”. To re-enable the check, edit it again and check that same box.

Sometimes you may need to disable all the checks to a particular datacenter or for a particular server or service. You can do it one at a time as described above but that can be a click-fest if you have a large number of checks to disable. Our new features allow you to easily disable all of your checks at once, or to disable a group of them based on some powerful filtering capability (described more below).

Disabling All Checks
You can disable and re-enable all your checks with just a couple of clicks. In the “Account Settings” – “General Settings” tab, you’ll see a link for “Disable All Checks”. Click on it and all your currently enabled checks will be immediately disabled. To re-enable the checks, click on the new link that appeared that says “Re-enable Checks”. Please note that this will only re-enable checks that have been disabled using the “Disable All Checks” link. If you disabled a check using one of the methods described above in the “Disabling a Single Check” section of this post, the check will remain disabled.

Disabling all checks can be useful to silence monitoring and notifications during major outages, planned maintenance, or to quiet logs when troubleshooting.

Disabling Multiple Checks
Our new disable feature has some powerful filtering that can help you disable all checks where the label, type, and/or target are similar. Clicking on the “Show optional filters” link in the “Account Settings” – “General Settings” tab will display the available filter fields of “Type”, “Label”, and “Target”. After choosing the dropdown or typing your desired filters in the fields there, you need to click on the “Disable All Checks” link and NodePing will disable all currently enabled checks that match your filters.

If you’d like to disable all your HTTP Content checks, you can choose it from the “Type” drop down.

If all the checks you need to disable are named similarly (example: “Server1: website A”, “Server1: website B”, “Server1: website C”), you can disable all of them by putting “Server1” in the “Label” field. The matching works on any part of the label.

If a particular server is failing, you can disable all checks (no matter what type or label) that point to that server by putting the name or IP address used in the check “Target” field. For example, I can disable all checks that point to all hosts by typing “” in that field. It will disable checks to ‘’ and ‘’, no matter what the check type is.

The filters are additive so if you choose the “HTTP” type and type something in the “Label” field, only HTTP checks that match that label will be disabled.

Use the “Re-enable Checks” link to re-enable checks that were previously disabled using the “Disable All Checks” link and filters.

These filters have superpowers too, thanks to regex. You can geek out and provide a valid javascript regex expression for each filter in our UI or API. Run a curl one-liner to our API before your maintenance fires off to disable some checks and then re-enable them when it’s done. See our API reference for details.

NodePing is committed to bring you more functionality like these new disable check features available in all accounts now. If you don’t yet have a NodePing server monitoring account, we encourage you to sign up for a free, 15-day trial and see how our fast, accurate uptime monitoring can help you keep your services up and available.

NTP Monitoring

Host clock synchronization is important for server clusters and many other services. Having a node with the system clock drifting can cause all kinds of hard-to-troubleshoot issues (I’m looking at you, Cassandra). Thankfully NTP (Network Time Protocol) has been there since before 1985 to help us keep our clocks within a few milliseconds of each other.

If you run your own NTP servers or use someone else’s for mission critical services, you need to monitor that they are up and running. NodePing’s new NTP check can make sure the NTP services you rely on are available and responding and will send you actionable notifications when they aren’t.

Alternatively, if you have a private NTP server that should not be available to the relentless interwebs, we can monitor it’s expected silence well. If your private NTP server starts responding to the world, we’ll send you an alert that the dog got out of the yard.

NTP monitoring is available on all account plans today. If you don’t have a NodePing account yet, sign up for your free, 15-day trial today and we’ll keep an eye on your NTP servers for you.