Uptime Robot has a very easy-to-use API.
Responses are provided as XML, JSON or JSON-P.
It lets you get the details of your monitors, logs and create/edit monitors + alert contacts (or remove existing ones).
That's all.
Authentication
HTTP Basic Access Authentication is used for verifying accounts.
There are 2 types of apiKeys for reaching the data:- account-specific apiKey which allows using all the API methods on all the monitors of an account
- monitor-specific apiKeys which allows using only the
getMonitors
method for the given monitor
Which apiKey type to use?
account-specific apiKey is good for pulling data for more than 1 monitors (like listing the stats of all monitors) and/or adding-editing-deleting monitors.
monitor-specific apiKeys are good for pulling data for a single monitor without revealing your main apiKey (account-specific apiKey). For ex: you can use monitor-specific apiKeys in client websites (so you'll still be able to pull data and the client will only be able to see the monitor-specific apiKey).
Where to find the apiKeys?
They are found under "My Settings" page.
While making a request, send the apiKey in your request just like:
apiKey=u956-afus321g565fghr519
(check example requests below).
Formats
Responses can either be XML or JSON. Just mention the preferred format as:
format=xml
or format=json
Once a JSON response is requested, the response comes with a callback function named jsonUptimeRobotApi
by default, just like:
jsonUptimeRobotApi({...});
If you only need the raw JSON response without a function wrapper, send the noJsonCallback
parameter with a value of 1
, like:
noJsonCallback=1
will result in {...}
Methods
Methods are defined just after the API URL (for ex: https://api.uptimerobot.com/methodName). And, here they are:
getAccountDetails
Account details (max number of monitors that can be added and number of up/down/paused monitors) can be grabbed using this method.
Parameters- apiKey - required
XML
A sample request for getting the account details:
https://api.uptimerobot.com/getAccountDetails?apiKey=u956-afus321g565fghr519&format=xml
JSON
A sample request for getting the account details:
https://api.uptimerobot.com/getAccountDetails?apiKey=u956-afus321g565fghr519&format=json
jsonUptimeRobotApi( { "stat": "ok", "account": { "monitorLimit": "100", "monitorInterval": "1", "upMonitors": "35", "downMonitors": "9", "pausedMonitors": "11" } } )
getMonitors
This is a Swiss-Army knife type of a method for getting any information on monitors.
By default, it lists all the monitors in a user's account, their friendly names, types (http, keyword, port, etc.), statuses (up, down, etc.) and uptime ratios.
There are optional parameters which lets the getMonitors
method to output information on any given monitors rather than all of them.
And also, parameters exist for getting the notification logs (alerts) for each monitor and even which alert contacts were alerted on each notification.
Parameters:- apiKey - required
- monitors - optional (if not used, will return all monitors in an account. Else, it is possible to define any number of monitors with their IDs like:
monitors=15830-32696-83920
) - types - optional (if not used, will return all monitors types (HTTP, keyword, ping..) in an account. Else, it is possible to define any number of monitor types like:
types=1-3-4
) - statuses - optional (if not used, will return all monitors statuses (up, down, paused) in an account. Else, it is possible to define any number of monitor statuses like:
statuses=2-9
) - customUptimeRatio - optional (defines the number of days to calculate the uptime ratio(s) for. Ex:
customUptimeRatio=7-30-45
to get the uptime ratios for those periods) - logs - optional (defines if the logs of each monitor will be returned. Should be set to
1
for getting the logs. Default is0
) - logsLimit - optional (the number of logs to be returned (descending order). If empty, all logs are returned.
- responseTimes - optional (defines if the response time data of each monitor will be returned. Should be set to
1
for getting them. Default is0
) - responseTimesLimit - optional (the number of response time logs to be returned (descending order). If empty, last 24 hours of logs are returned (if
responseTimesStartDate
andresponseTimesEndDate
are not used). - responseTimesAverage - optional (by default, response time value of each check is returned. The API can return average values in given minutes. Default is
0
. For ex: the Uptime Robot dashboard displays the data averaged/grouped in 30 minutes) - responseTimesStartDate - optional and works only for the Pro Plan as 24 hour+ logs are kept only in the Pro Plan (starting date of the response times, formatted as
2015-04-23
and must be used withresponseTimesEndDate
) (can only be used ifmonitors
parameter is used with a singlemonitorID
andresponseTimesEndDate - responseTimesStartDate
can't be more than 7 days) - responseTimesEndDate - optional and works only for the Pro Plan as 24 hour+ logs are kept only in the Pro Plan (ending date of the response times, formatted as
2015-04-23
and must be used withresponseTimesStartDate
) (can only be used ifmonitors
parameter is used with a singlemonitorID
andresponseTimesEndDate - responseTimesStartDate
can't be more than 7 days) - alertContacts - optional (defines if the notified alert contacts of each notification will be returned. Should be set to
1
for getting them. Default is0
. Requires logs to be set to1
) - showMonitorAlertContacts - optional (defines if the alert contacts set for the monitor to be returned. Default is
0
) - showTimezone - optional (defines if the user's timezone should be returned. Should be set to
1
for getting it. Default is0
) - offset - optional (used for pagination. Defines the record to start paginating. Default is
0
) - limit - optional (used for pagination. Defines the max number of records to return for the response. Default and max. is
50
) - search - optional (a keyword of your choice to search within
monitorURL
andmonitorFriendlyName
and get filtered results)
XML
A sample request which gets all the data about monitors with specified IDs:
https://api.uptimerobot.com/getMonitors?apiKey=u956-afus321g565fghr519&logs=1&alertContacts=1&responseTimes=1&responseTimesAverage=180&monitors=15830-32696&customUptimeRatio=30&format=xml
The response would be:
JSON
A sample request which gets all the data about monitors with specified IDs:
https://api.uptimerobot.com/getMonitors?apiKey=u956-afus321g565fghr519&logs=1&alertContacts=1&responseTimes=1&responseTimesAverage=180&monitors=15830-32696&format=json
The response would be:
jsonUptimeRobotApi({ "stat":"ok", "offset":"0", "limit":"50", "total":"2", "monitors":{ "monitor":[ { "id":"128795", "friendlyname":"Yahoo", "url":"http://www.yahoo.com/", "type":"1", "subtype":"", "keywordtype":"0", "keywordvalue":"", "httpusername":"", "httppassword":"", "port":"", "interval":"300", "status":"2", "alltimeuptimeratio":"99.98", "customuptimeratio":"100.00", "alertcontact":[ { "id":"4631", "type":"2", "value":"[email protected]", "threshold":"2", "recurrence":"1" }, { "id":"2420", "type":"3", "value":"umutm", "threshold":"0", "recurrence":"0" } ], "log":[ { "type":"2", "datetime":"09/25/2011 16:12:44", "alertcontact":[ { "type":"0", "value":"[email protected]" }, { "type":"3", "value":"umutm" } ] }, { "type":"1", "datetime":"09/25/2011 16:11:44", "alertcontact":[ { "type":"0", "value":"[email protected]" }, { "type":"3", "value":"umutm" } ] } ], "responsetime":[ { "datetime":"02/04/2014 11:30:41", "value":"405" }, { "datetime":"02/04/2014 12:00:41", "value":"516" }, { "datetime":"02/04/2014 12:30:41", "value":"780" } ] }, { "id":"128796", "friendlyname":"domain", "url":"http://www.domain.com/", "type":"1", "subtype":"", "keywordtype":"0", "keywordvalue":"", "httpusername":"", "httppassword":"", "port":"", "interval":"300", "status":"2", "alltimeuptimeratio":"99.94", "customtimeuptimeratio":"89.51", "alertcontact":[ { "id":"2420", "type":"3", "value":"umutm", "threshold":"2", "recurrence":"1" } ], "log":[ { "type":"2", "datetime":"08/30/2011 16:11:15", "alertcontact":[ { "type":"0", "value":"[email protected]" }, { "type":"3", "value":"umutm" } ] }, { "type":"1", "datetime":"08/30/2011 16:09:30", "alertcontact":[ { "type":"0", "value":"[email protected]" }, { "type":"3", "value":"umutm" } ] } ], "responsetime":[ { "datetime":"02/04/2014 11:48:41", "value":"405" }, { "datetime":"02/04/2014 12:18:41", "value":"516" }, { "datetime":"02/04/2014 12:48:41", "value":"780" } ] } ] } })
newMonitor
New monitors of any type can be created using this method.
Parameters- apiKey - required
- monitorFriendlyName - required
- monitorURL - required
- monitorType - required
- monitorSubType - optional (required for port monitoring)
- monitorPort - optional (required for port monitoring)
- monitorKeywordType - optional (required for keyword monitoring)
- monitorKeywordValue - optional (required for keyword monitoring)
- monitorHTTPUsername - optional
- monitorHTTPPassword - optional
- monitorAlertContacts - optional (the alert contacts to be notified when the monitor goes up/down.Multiple
alertContactID
s can be sent likemonitorAlertContacts=457_0_0-373_5_0-8956_2_3
wherealertContactIDs
are seperated with - andthreshold
+recurrence
are seperated with _. For ex:monitorAlertContacts=457_5_0
refers to 457 being thealertContactID
, 5 being thethreshold
and 0 being therecurrence
. As the threshold and recurrence is only available in the Pro Plan, they are always 0 in the Free Plan) - monitorInterval - optional (in minutes)
XML
A sample request which creates a HTTP monitor with 2 alert contacts:
https://api.uptimerobot.com/newMonitor?apiKey=u956-afus321g565fghr519&monitorFriendlyName=Google&monitorURL=http://www.google.com&monitorType=1&monitorAlertContacts=448-716&format=xml
JSON
A sample request which creates a HTTP monitor with 2 alert contacts:
https://api.uptimerobot.com/newMonitor?apiKey=u956-afus321g565fghr519&monitorFriendlyName=Google&monitorURL=http://www.google.com&monitorType=1&monitorAlertContacts=448-716&format=json
jsonUptimeRobotApi({ "stat": "ok", "monitor":{ "id":"128798" } })
editMonitor
Monitors can be edited using this method.
Important: The type of a monitor can not be edited (like changing a HTTP monitor into a Port monitor). For such cases, deleting the monitor and re-creating a new one is adviced.
Parameters- apiKey - required
- monitorID - required
- monitorStatus - optional
- monitorFriendlyName - optional
- monitorURL -optional
- monitorType -optional
- monitorSubType -optional (used only for port monitoring)
- monitorPort -optional (used onlyfor port monitoring)
- monitorKeywordType - optional (used only for keyword monitoring)
- monitorKeywordValue - optional (used only for keyword monitoring)
- monitorHTTPUsername - optional (in order to remove any previously added username, simply send the value empty like
monitorHTTPUsername=
) - monitorHTTPPassword - optional (in order to remove any previously added password, simply send the value empty like
monitorHTTPPassword=
) - monitorAlertContacts - optional (the alert contacts to be notified when the monitor goes up/down.Multiple
alertContactID
s can be sent likemonitorAlertContacts=457_0_0-373_5_0-8956_2_3
wherealertContactIDs
are seperated with - andthreshold
+recurrence
are seperated with _. For ex:monitorAlertContacts=457_5_0
refers to 457 being thealertContactID
, 0 being thethreshold
and 0 being therecurrence
. As the threshold and recurrence is only available in the Pro Plan, they are always 0 in the Free Plan) (in order to remove any previously added alert contacts, simply send the value empty likemonitorAlertContacts=
) - monitorInterval - optional (in minutes)
XML
A sample request which changes the "Friendly Name" of a monitor:
https://api.uptimerobot.com/editMonitor?apiKey=u956-afus321g565fghr519&monitorID=128798&monitorFriendlyName=GoogleHomepage&format=xml
JSON
A sample request which changes the "Friendly Name" of a monitor:
https://api.uptimerobot.com/editMonitor?apiKey=u956-afus321g565fghr519&monitorID=128798&monitorFriendlyName=GoogleHomepage&format=json
jsonUptimeRobotApi({ "stat": "ok", "monitor":{ "id":"128798" } })
deleteMonitor
Monitors can be deleted using this method.
Parameters:- apiKey - required
- monitorID - required
XML
A sample request which deletes a monitor:
https://api.uptimerobot.com/deleteMonitor?apiKey=u956-afus321g565fghr519&monitorID=128798&format=xml
JSON
A sample request which deletes a monitor:
https://api.uptimerobot.com/deleteMonitor?apiKey=u956-afus321g565fghr519&monitorID=128798&format=json
jsonUptimeRobotApi({ "stat": "ok", "monitor":{ "id":"128798" } })
resetMonitor
Monitors can be reset (deleting all stats and response time data) using this method.
Parameters:- apiKey - required
- monitorID - required
XML
A sample request which resets a monitor:
https://api.uptimerobot.com/resetMonitor?apiKey=u956-afus321g565fghr519&monitorID=128798&format=xml
JSON
A sample request which resets a monitor:
https://api.uptimerobot.com/resetMonitor?apiKey=u956-afus321g565fghr519&monitorID=128798&format=json
jsonUptimeRobotApi({ "stat": "ok", "monitor":{ "id":"128798" } })
getAlertContacts
The list of alert contacts can be called with this method.
Parameters- apiKey - required
- alertcontacts - optional (if not used, will return all alert contacts in an account. Else, it is possible to define any number of alert contacts with their IDs like:
alertcontacts=236-1782-4790
) - offset - optional (used for pagination. Defines the record to start paginating. Default is
0
) - limit - optional (used for pagination. Defines the max number of records to return for the response. Default and max. is
50
)
XML
A sample request which gets all the data about alert contacts with specified IDs:
https://api.uptimerobot.com/getAlertContacts?apiKey=u956-afus321g565fghr519&alertcontacts=236&format=xml
JSON
A sample request which gets all the data about alert contacts with specified IDs:
https://api.uptimerobot.com/getAlertContacts?apiKey=u956-afus321g565fghr519&alertcontacts=236&format=json
jsonUptimeRobotApi({ "stat": "ok", "offset": "0", "limit": "50", "total": "1", "alertcontacts": { "alertcontact": [ { "id": "236", "value": "[email protected]", "friendlyname": "My E-mail", "type": "2", "status": "2" } ] } })
newAlertContact
New alert contacts of any type (mobile/SMS alert contacts are not supported yet) can be created using this method.
The alert contacts created using the API are validated with the same way as they were created from uptimerobot.com (activation link for e-mails, tc.).
Parameters:- apiKey - required
- alertContactType - required
- alertContactValue - required
- alertContactFriendlyName - optional
XML
A sample request which creates an e-mail alert contact:
https://api.uptimerobot.com/newAlertContact?apiKey=u956-afus321g565fghr519&alertContactType=2&[email protected]&format=xml
JSON
A sample request which gets all the data about alert contacts with specified IDs:
https://api.uptimerobot.com/newAlertContact?apiKey=u956-afus321g565fghr519&alertContactType=2&[email protected]&format=json
jsonUptimeRobotApi({ "stat": "ok", "alertcontact": { "id": "4561", "status": "0" } })
deleteAlertContact
Alert contacts can be deleted using this method.
Parameters:- apiKey - required
- alertContactID - required
XML
A sample request which deletes an alert contact:
https://api.uptimerobot.com/deleteAlertContact?apiKey=u956-afus321g565fghr519&alertContactID=236&format=xml
JSON
A sample request which gets all the data about alert contacts with specified IDs:
https://api.uptimerobot.com/deleteAlertContact?apiKey=u956-afus321g565fghr519&alertContactID=236&format=json
jsonUptimeRobotApi({ "stat": "ok", "alertcontact": { "id": "236" } })
Parameters
Objects | Values | Extra Details |
---|---|---|
stat |
|
exists only for JSON responses to show if any records are returned or not. |
offset | integer | the starting record for getMonitors and getAlertContacts methods |
limit | integer | the number of records to be returned for getMonitors and getAlertContacts methods |
total | integer | the total number of records for getMonitors and getAlertContacts methods |
account>monitorLimit | integer | the max number of monitors that can be created for the account |
account>monitorInterval | integer | the min monitoring interval (in minutes) supported by the account |
account>upMonitors | integer | the number of "up" monitors |
account>downMonitors | integer | the number of "down" monitors |
account>pausedMonitors | integer | the number of "paused" monitors |
monitor>id | integer | the ID of the monitor (can be used for monitor-specific requests). |
monitor>friendlyname | text | the friendly name of the monitor. |
monitor>url | URL or IP | the URL/IP of the monitor. |
monitor>type |
|
the type of the monitor. |
monitor>subtype |
|
used only for "Port monitoring (monitor>type = 4)" and shows which pre-defined port/service is monitored or if a custom port is monitored. |
monitor>keywordtype |
|
used only for "Keyword monitoring (monitor>type = 4)" and shows "if the monitor will be flagged as down when the keyword exists or not exists". |
monitor>keywordvalue | text | the value of the keyword. |
monitor>httpusername | text | used for password-protected web pages (HTTP Basic Auth). Available for HTTP and keyword monitoring. |
monitor>httppassword | text | used for password-protected web pages (HTTP Basic Auth). Available for HTTP and keyword monitoring. |
monitor>port | integer | used only for "Port monitoring (monitor>type = 4)" and shows the port monitored. |
monitor>interval | integer | the interval for the monitoring check (5 minutes by default). |
monitor>status |
|
the status of the monitor. When used with the editMonitor method 0 (to pause) or 1 (to start) can be sent. |
monitor>alltimeuptimeratio | rational number (with 2 decimals) |
the uptime ratio of the monitor calculated since the monitor is created. |
monitor>customuptimeratio | rational number (with 2 decimals) |
the uptime ratio of the monitor for the given periods (if there are more than 1 periods, then the values are seperate with "-") |
log>type |
|
the value of the keyword. |
log>datetime | datetime | the date and time of the log (inherits the user's timezone setting). |
alertcontact>id | integer | the ID of the alert contact. |
alertcontact>type |
|
the type of the alert contact notified (Zapier, HipChat and Slack are not supported in the newAlertContact method yet). |
alertcontact>value | text | alert contact's address/phone. |
alertcontact>friendlyname | text | friendly name of the alert contact (for making it easier to distinguish from others). |
alertcontact>status |
|
the status of the alert contact. |
alertcontact>threshold | 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,20,30,35,40,45,50,55,60,70,80,90,100,110,120,150,180,210,240,270,300,360,420,480,540,600,660,720 | the x value that is set to define "if down for x minutes, alert every y minutes. |
alertcontact>recurrence | 0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,20,30,35,40,45,50,55,60 | the y value that is set to define "if down for x minutes, alert every y minutes. |
Error Messages
Errors are displayed as:
XMLjsonUptimeRobotApi( { "stat": "fail", "id": "101", "message": "apiKey is wrong" } )
ID | Details |
---|---|
100 | apiKey not mentioned or in a wrong format |
101 | apiKey is wrong |
102 | format is wrong (should be xml or json) |
103 | No such method exists |
200 | monitorID(s) should be integers |
201 | monitorUrl is invalid |
202 | monitorType is invalid |
203 | monitorSubType is invalid |
204 | monitorKeywordType is invalid |
205 | monitorPort is invalid |
206 | monitorFriendlyName is required |
207 | The monitor already exists |
208 | monitorSubType is required for this type of monitors |
209 | monitorKeyWordType and monitorKeyWordValue are required for this type of monitors |
210 | monitorID doesn't exist |
211 | monitorID is required |
212 | The account has no monitors |
213 | At least one of the parameters to be edited are required |
214 | monitorHTTPUsername and monitorHTTPPassword should both be empty or have values |
215 | monitor specific apiKeys can only use getMonitors method |
216 | A user with this e-mail already exists |
217 | userFirstLastName and userEmail are both required |
218 | userEmail is not in the right e-mail format |
219 | This account is not authorized to create users |
220 | monitorAlertContacts value is wrong |
221 | The account has no alert contacts |
222 | alertcontactID(s) should be integers |
223 | alertContactType and alertContactValue are both required |
224 | This alertContactType is not supported" |
225 | The alert contact already exists |
226 | The alert contact is not following @uptimerobot Twitter user. It is required so that the Twitter direct messages (DM) can be sent |
227 | The Boxcar user mentioned does not exist |
228 | The Boxcar alert contact couldn't be added, please try again later |
229 | alertContactID doesn't exist |
230 | alertContactValue should be a valid e-mail for this alertContactType |
Sample PHP Code
For a quick start, here is a simple PHP code to retrieve the alltimeuptimeratio of a desired monitor:
<?php /*Note: You'll need the ID of the monitor. For that, simply go to "https://api.uptimerobot.com/getMonitors?apiKey=yourApiKey" and get the ID of the monitor to be queried.*/ /*And, this code requires PHP 5+ or PHP 4 with SimpleXML enabled.*/ /*Variables - Start*/ $apiKey = "yourApiKey"; /*replace with your apiKey*/ $monitorID = 1111111; /*replace with your monitorID*/ $url = "https://api.uptimerobot.com/getMonitors?apiKey=" . $apiKey . "&monitors=" . $monitorID . "&format=xml"; /*Variables - End*/ /*Curl Request - Start*/ $c = curl_init($url); curl_setopt($c, CURLOPT_RETURNTRANSFER, true); $responseXML = curl_exec($c); curl_close($c); /*Curl Request - End*/ /*XML Parsing - Start*/ $xml = simplexml_load_string($responseXML); foreach($xml->monitor as $monitor) { echo $monitor['alltimeuptimeratio']; } /*XML Parsing - End*/ ?>
Unofficial API Resources
Here is a list of API-related resources created by Uptime Robot users:- Upscuits - uptime widget (demo) (by @pixelbak)
- jQuery plugin to display uptime (by @shreyaspurohit)
- PHP wrapper (by watchful.li)
- PHP wrapper (by @ckdarby)
- PHP wrapper (by @CodingOurWeb)
- StatusPage with PHP (demo) (by @HeadTalker)
- StatusPage - Public Status Page with PHP (demo) (by Spencer Lowe)
- SMonitor (PHP script that lists all monitors) (demo) (by @Sakretsos)
- PHP-powered dashboard (demo) (by Adam Matthews)
- Laravel (PHP) wrapper (by Graham Campbell)
- Python wrapper for Uptime Robot API (by Arteria)
- Django wrapper for Uptime Robot API (by Arteria)
- Declarative configuration library for Uptime Robot (Python) (by Anton Tolchanov)
- Uptime Robot API client for Ruby (by @sgwr_dts)
- Go library for Uptime Robot (by Jimdo)
- Uptime Robot API client for Go (by Ringo De Smet)
- .NET Uptime Robot API Client (by GBSHouse.com)
- .NET wrapper for Uptime Robot API (by @cmaneu)
- GURobot - Groovy Uptime Robot API Client (by @josebovet)
- UptimeSharp - C# assembly (source) (by @artistandsocial)
- Uptime Robot command-line utility (by @schirmacher)
- Classic ASP example for listing monitors (.zip) (by @coax)
- WordPress Dashboard Widget (by @brian_c_welch)
- WordPress Dashboard Widget For Uptime Robot (by @CreativeBoulder & @CodeClarity)
- Drupal Widget (by Martin Postma)
- Piwik Plugin for Uptime Robot (by @JoachimBarthel)
- Twitter Bot for Uptime Robot (by Spencer Lowe)
- Chrome Extension (by @TravelTechGuy)
- Chrome Extension (by Shreyas Purohit)
- UptimeRobot Android (by Balazs Hollosi)
- UptimeRobot Monitor for iPhone (free) (by @Massimo_Ghielmi)
- Uptime Bot - iPhone/iPad (paid) (by @Inspira4Studio)
- UptimeRobot for iPhone (paid)
- UptimeRobot Monitor For Android (by Mowd)
- Android App For Uptime Robot (.apk file) (by @and_n0b0dy)
- UptimeRobot for Windows Phone
- Pebble Smart Watch App For Uptime Robot (source - by LogicalPixels)
- Dashing.io Widget For Uptime Robot (by Chris Crewdson)