API

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.

• 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.

• apiKey - required

Sample Request And Response

									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.

• 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 is 0)
• 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 is 0)
• responseTimesLimit - optional (the number of response time logs to be returned (descending order). If empty, last 24 hours of logs are returned (if responseTimesStartDate and responseTimesEndDate 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 with responseTimesEndDate) (can only be used if monitors parameter is used with a single monitorID and responseTimesEndDate - 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 with responseTimesStartDate) (can only be used if monitors parameter is used with a single monitorID and responseTimesEndDate - 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 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)
• search - optional (a keyword of your choice to search within monitorURL and monitorFriendlyName and get filtered results)

Sample Request And Response

								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.

• 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_0_0-373_5_0-8956_2_3 where alertContactIDs are seperated with - and threshold + recurrence are seperated with _. For ex: monitorAlertContacts=457_5_0 refers to 457 being the alertContactID, 5 being the threshold and 0 being the recurrence. As the threshold and recurrence is only available in the Pro Plan, they are always 0 in the Free Plan)
• monitorInterval - optional (in minutes)

Sample Request And Response

								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.

• 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_0_0-373_5_0-8956_2_3 where alertContactIDs are seperated with - and threshold + recurrence are seperated with _. For ex: monitorAlertContacts=457_5_0 refers to 457 being the alertContactID, 0 being the threshold and 0 being the recurrence. 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 like monitorAlertContacts=)
• monitorInterval - optional (in minutes)

Sample Request And Response

								jsonUptimeRobotApi({
									"stat": "ok",
									"monitor":{
										"id":"128798"
									}
								})
							

deleteMonitor

Monitors can be deleted using this method.

• apiKey - required
• monitorID - required

Sample Request And Response

								jsonUptimeRobotApi({
									"stat": "ok",
									"monitor":{
										"id":"128798"
									}
								})
							

resetMonitor

Monitors can be reset (deleting all stats and response time data) using this method.

• apiKey - required
• monitorID - required

Sample Request And Response

								jsonUptimeRobotApi({
									"stat": "ok",
									"monitor":{
										"id":"128798"
									}
								})
							

getAlertContacts

The list of alert contacts can be called with this method.

• 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)

Sample Request And Response

								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.).

• apiKey - required
• alertContactType - required
• alertContactValue - required
• alertContactFriendlyName - optional

Sample Request And Response

								jsonUptimeRobotApi({
									"stat": "ok",
									"alertcontact": {
										"id": "4561",
										"status": "0"
									}
								})
							

deleteAlertContact

Alert contacts can be deleted using this method.

• apiKey - required
• alertContactID - required

Sample Request And Response

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

Parameters

Error Messages

Errors are displayed as:

							jsonUptimeRobotApi(
								{
									"stat": "fail",
									"id": "101",
									"message": "apiKey is wrong"
								}
							)
						

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

• 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)