API

Integrate Uptime Robot into your sites and apps..

Introduction

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: http://api.uptimerobot.com/methodName). And, here they are:

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)
  • 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 is 0)
  • responseTimes - optional (defines if the response time data of each monitor will be returned. Should be set to 1 for getting them. Default is 0)
  • 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)
  • alertContacts - optional (defines if the notified alert contacts of each notification will be returned. Should be set to 1 for getting them. Default is 0. 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 is 0)
  • 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 monitors with specified IDs:

http://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:

http://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": "",
                                                                        "status": "2",
                                                                        "alltimeuptimeratio": "99.98",
                                                                        "customuptimeratio": "100.00",
                                                                        "alertcontact": [
                                                                            {
                                                                                "id": "4631",
                                                                                "type": "2",
                                                                                "value": "uptime@webresourcesdepot.com"
                                                                            },
                                                                            {
                                                                                "id": "2420",
                                                                                "type": "3",
                                                                                "value": "umutm"
                                                                            }
                                                                        ],
                                                                        "log": [
                                                                            {
                                                                                "type": "2",
                                                                                "datetime": "09/25/2011 16:12:44",
                                                                                "alertcontact": [
                                                                                    {
                                                                                        "type": "0",
                                                                                        "value": "uptime@webresourcesdepot.com"
                                                                                    },
                                                                                    {
                                                                                        "type": "3",
                                                                                        "value": "umutm"
                                                                                    }
                                                                                ]
                                                                            },
                                                                            {
                                                                                "type": "1",
                                                                                "datetime": "09/25/2011 16:11:44",
                                                                                "alertcontact": [
                                                                                    {
                                                                                        "type": "0",
                                                                                        "value": "uptime@webresourcesdepot.com"
                                                                                    },
                                                                                    {
                                                                                        "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": "WebResourcesDepot",
                                                                        "url": "http://www.webresourcesdepot.com/",
                                                                        "type": "1",
                                                                        "subtype": "",
                                                                        "keywordtype": "0",
                                                                        "keywordvalue": "",
                                                                        "httpusername": "",
                                                                        "httppassword": "",
                                                                        "port": "",
                                                                        "status": "2",
                                                                        "alltimeuptimeratio": "99.94",
                                                                        "customtimeuptimeratio": "89.51",
                                                                        "alertcontact": [
                                                                            {
                                                                                "id": "2420",
                                                                                "type": "3",
                                                                                "value": "umutm"
                                                                            }
                                                                        ],
                                                                        "log": [
                                                                            {
                                                                                "type": "2",
                                                                                "datetime": "08/30/2011 16:11:15",
                                                                                "alertcontact": [
                                                                                    {
                                                                                        "type": "0",
                                                                                        "value": "uptime@webresourcesdepot.com"
                                                                                    },
                                                                                    {
                                                                                        "type": "3",
                                                                                        "value": "umutm"
                                                                                    }
                                                                                ]
                                                                            },
                                                                            {
                                                                                "type": "1",
                                                                                "datetime": "08/30/2011 16:09:30",
                                                                                "alertcontact": [
                                                                                    {
                                                                                        "type": "0",
                                                                                        "value": "uptime@webresourcesdepot.com"
                                                                                    },
                                                                                    {
                                                                                        "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 alertContactIDs can be sent like monitorAlertContacts=457-373-8956)
  • monitorInterval - optional (in minutes)

XML

A sample request which creates a HTTP monitor with 2 alert contacts:

http://api.uptimerobot.com/newMonitor?apiKey=u956-afus321g565fghr519&monitorFriendlyName=Google&monitorURL=http://www.google.com&monitorType=1&monitorAlertContacts=448-716&format=xml

The response would be:

														
                                                    

 

JSON

A sample request which creates a HTTP monitor with 2 alert contacts:

http://api.uptimerobot.com/newMonitor?apiKey=u956-afus321g565fghr519&monitorFriendlyName=Google&monitorURL=http://www.google.com&monitorType=1&monitorAlertContacts=448-716&format=json

The response would be:

                                                        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 alertContactIDs can be sent like monitorAlertContacts=457-373-8956) (in order to remove any previously added alert contacts, simply send the value empty like monitorAlertContacts=)
  • monitorInterval - optional (in minutes)

XML

A sample request which changes the "Friendly Name" of a monitor:

http://api.uptimerobot.com/editMonitor?apiKey=u956-afus321g565fghr519&monitorID=128798&monitorFriendlyName=GoogleHomepage&format=xml

The response would be:

                                                        
                                                    

 

JSON

A sample request which changes the "Friendly Name" of a monitor:

http://api.uptimerobot.com/editMonitor?apiKey=u956-afus321g565fghr519&monitorID=128798&monitorFriendlyName=GoogleHomepage&format=json

The response would be:

                                                        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:

http://api.uptimerobot.com/deleteMonitor?apiKey=u956-afus321g565fghr519&monitorID=128798&format=xml

The response would be:

                                                        
                                                    

 

JSON

A sample request which deletes a monitor:

http://api.uptimerobot.com/deleteMonitor?apiKey=u956-afus321g565fghr519&monitorID=128798&format=json

The response would be:

                                                        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:

http://api.uptimerobot.com/getAlertContacts?apiKey=u956-afus321g565fghr519&alertcontacts=236&format=xml

The response would be:

                                                    	
                                                        	
                                                        
                                                    

 

JSON

A sample request which gets all the data about alert contacts with specified IDs:

http://api.uptimerobot.com/getAlertContacts?apiKey=u956-afus321g565fghr519&alertcontacts=236&format=json

The response would be:

 

                                                        jsonUptimeRobotApi({
                                                            "stat": "ok",
                                                            "offset": "0",
                                                            "limit": "50",
                                                            "total": "1",
                                                            "alertcontacts": {
                                                                "alertcontact": [
                                                                    {
                                                                        "id": "236",
                                                                        "value": "uptime@webresourcesdepot.com",
                                                                        "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

XML

A sample request which creates an e-mail alert contact:

http://api.uptimerobot.com/newAlertContact?apiKey=u956-afus321g565fghr519&alertContactType=2&alertContactValue=uptime@webresourcesdepot.com&format=xml

The response would be:

                                                        
                                                    

 

JSON

A sample request which gets all the data about alert contacts with specified IDs:

http://api.uptimerobot.com/newAlertContact?apiKey=u956-afus321g565fghr519&alertContactType=2&alertContactValue=uptime@webresourcesdepot.com&format=json

The response would be:

                                                        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:

http://api.uptimerobot.com/deleteAlertContact?apiKey=u956-afus321g565fghr519&alertContactID=236&format=xml

The response would be:

                                                        
                                                    

 

JSON

A sample request which gets all the data about alert contacts with specified IDs:

http://api.uptimerobot.com/deleteAlertContact?apiKey=u956-afus321g565fghr519&alertContactID=236&format=json

The response would be:

                                                        jsonUptimeRobotApi({
                                                            "stat": "ok",
                                                            "alertcontact": {
                                                                "id": "236"
                                                            }
                                                        })
                                                    

Parameters

Objects Values Extra Details
stat
  • ok
  • fail
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
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
  • 1 - HTTP(s)
  • 2 - Keyword
  • 3 - Ping
  • 4 - Port
the type of the monitor.
monitor>subtype
  • 1 - HTTP (80)
  • 2 - HTTPS (443)
  • 3 - FTP (21)
  • 4 - SMTP (25)
  • 5 - POP3 (110)
  • 6 - IMAP (143)
  • 99 - Custom Port
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
  • 1 - exists
  • 2 - not exists
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>status
  • 0 - paused
  • 1 - not checked yet
  • 2 - up
  • 8 - seems down
  • 9 - down
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
  • 1 - down
  • 2 - up
  • 99 - paused
  • 98 - started
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
  • 1 - SMS
  • 2 - E-mail
  • 3 - Twitter DM
  • 4 - Boxcar
  • 5 - Web-Hook
  • 6 - Pushbullet
the type of the alert contact notified.
alertcontact>value text alert contact's address/phone.
alertcontact>status
  • 0 - not activated
  • 1 - paused
  • 2 - active
the status of the alert contact.

Error Messages

Errors are displayed as:

XML

                                                
                                            

 

JSON

                                                jsonUptimeRobotApi({
                                                    "stat": "ok",
                                                    "alertcontact": {
                                                        "id": "236"
                                                    }
                                                })
                                            
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 "http://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 	= "http://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*/
                                            ?>