The Pingdom API is a way for you to automate your interaction with the Pingdom system. With the API, you can create your own scripts or applications with most of the functionality you can find inside the Pingdom control panel.
The Pingdom API is RESTful and HTTP-based. Basically, this means that the communication is made through normal HTTP requests.
Authentication is needed in order to use the Pingdom API, and for this a Pingdom account is required. The credentials used for accessing the API are the same used to access the Pingdom control panel - in other words your email address and your password. You will also need an application key.
The authentication method for user credentials is HTTP Basic Access Authentication (encrypted over HTTPS). This means you will provide your credentials every time you make a request. No sessions are used.
For further information on HTTP Basic Access Authentication, take a look at: http://en.wikipedia.org/wiki/HTTP_authentication
You generate your application key inside the Pingdom control panel. It is supposed to be unique on an application basis, not user basis. This means that if you produce an application and then distribute it to the public, all users of this application should use the same application key.
The application key is provided as a normal HTTP header in your request. Here is an example:
App-Key: zoent8w9cbt810rsdkweir23vcxb87zrt5541
Feature only available for Team accounts. If you have multiple users connected to your account you can supply a HTTP header Account‑Email with the email address of the account from which you want to get information.
Example: Your account is [email protected]. The account on which you want to perform the API request is [email protected]. You would authenticate as [email protected], with the Account‑Email header set to [email protected].
> GET /checks HTTP/1.1
> Host: api.pingdom.com
> Authentication: Zm9vQGV4YW1wbGUuY29tOnBhc3N3b3Jk
> App-Key: 1234567890abcdef1234567890abcdef
> Account-Email: [email protected]
< HTTP/1.1 200 OK
< Content-Length: 13
< Content-Type: application/json
{"checks":[]}
The base server address is: https://api.pingdom.com
Please note that HTTPS is required. You will not be able to connect through unencrypted HTTP.
GET requests should provide their parameters as a query string, part of the URL.
POST, PUT and DELETE requests should provide their parameters as a query string. This should be part of the body, URL or a combination.
The encoding of the query string should be standard URL-encoding, as provided by various programming libraries.
The HTTP status code returned by a successful API request is defined in the documentation for that method. Usually, this will be 200 OK.
If something goes wrong, other codes may be returned. The API uses standard HTTP/1.1 status codes defined by RFC 2616.
All responses are sent JSON-encoded. The specific responses (successful ones) are described in the documentation section for each method.
However, if something goes wrong, our standard JSON error message (together with an appropriate status code) follows this format:
{
"error":{
"statuscode":403,
"statusdesc":"Forbidden",
"errormessage":"Something went wrong! This string describes what happened."
}
}
See http://en.wikipedia.org/wiki/Json for more information on JSON.
Please note that all attributes of a method response are not always present. A client application should never assume that a certain attribute is present in a response.
The Pingdom API has usage limits to avoid individual rampant applications degrading the overall user experience. There are two layers of limits, the first cover a shorter period of time and the second a longer period. This enables you to "burst" requests for shorter periods. There are two HTTP headers in every response describing your limits status.
The response headers are:
An example of the values of these headers:
In this case, we can see that the user has 394 requests left until the short limit is reached. In 3589 seconds, the short limit will be reset. In similar fashion, the long limit has 71994 requests left, and will be reset in 2591989 seconds.
If you feel restricted by these limits, please feel free to contact Pingdom support and request a higher limit. The limits are primarily here to protect the system from poorly coded applications, not to restrict you as a user.
Responses can be gzip-encoded on demand. This is nice if your bandwidth is limited, or if big results are causing performance issues.
To enable gzip, simply add the following header to your request:
Accept-Encoding: gzip
If you are building a web page using the Pingdom API, we recommend that you do all API request on the server side, and if possible cache them. If you get any substantial traffic, you do not want to call the API each time you get a page hit, since this may cause you to hit the request limit faster than expected. In general, whenever you can cache data, do so.
Some HTTP clients omit the authentication header, and make a second request with the header when they get a 401 Unauthorized response. Please make sure you send the credentials directly, to avoid unnecessary requests.
Should be simple enough. For example, don't check for the status of a check every other second. The highest check resolution is one minute. Checking more often than that won't give you much of an advantage.
Networks in general are unreliable, and particularly one as large and complex as the Internet. Your application should not assume it will get an answer. There may be timeouts.
"This is too much to read. I just want to get started right now! Give me a simple example!"
Here is a short example of how you can use the API with PHP. You need the cURL extension for PHP.
The example prints the current status of all your checks. This sample obviously focuses on Pingdom API code and does not worry about any potential problems connecting to the API, but your code should.
<?php
// Init cURL
$curl = curl_init();
// Set target URL
curl_setopt($curl, CURLOPT_URL, "https://api.pingdom.com/api/2.0/checks");
// Set the desired HTTP method (GET is default, see the documentation for each request)
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "GET");
// Set user (email) and password
curl_setopt($curl, CURLOPT_USERPWD, "[email protected]:password");
// Add a http header containing the application key (see the Authentication section of this document)
curl_setopt($curl, CURLOPT_HTTPHEADER, array("App-Key: zoent8w9cbt810rsdkweir23vcxb87zrt5541"));
// Ask cURL to return the result as a string
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
// Execute the request and decode the json result into an associative array
$response = json_decode(curl_exec($curl),true);
// Check for errors returned by the API
if (isset($response['error'])) {
print "Error: " . $response['error']['errormessage'] . "\n";
exit;
}
// Fetch the list of checks from the response
$checksList = $response['checks'];
// Print the names and statuses of all checks in the list
foreach ($checksList as $check) {
print $check['name'] . " is " . $check['status'] . "\n";
}
?>
Ubuntu Packages is up
Google is up
Pingdom is up
My server 1 is down
My server 2 is up
If you are running PHP on Windows, you need to be sure that you have installed the CA certificates for HTTPS/SSL to work correctly. Please see the cURL manual for more information. As a quick (but unsafe) workaround, you can add the following cURL option to ignore certificate validation.
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER, 0);
Below you can find descriptions and examples for all methods.
Returns a list of actions (alerts) that have been generated for your account.
/api/{version}/actions
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| from | Only include actions generated later than this timestamp. Format is UNIX time. | Integer | no | |
| to | Only include actions generated prior to this timestamp. Format is UNIX time. | Integer | no | |
| limit | Limits the number of returned results to the specified quantity. | Integer (max 300) | no | 100 |
| offset | Offset for listing. | Integer | no | 0 |
| checkids | Comma-separated list of check identifiers. Limit results to actions generated from these checks. | String | no | |
| contactids | Comma-separated list of contact identifiers. Limit results to actions sent to these contacts. | String | no | All contacts |
| status | Comma-separated list of statuses. Limit results to actions with these statuses. | String (sent, delivered, error, not_delivered, no_credits) | no | All statuses |
| via | Comma-separated list of via mediums. Limit results to actions with these mediums. | String (email, sms, twitter, iphone, android) | no | All mediums |
| Attribute | Description | Type |
|---|---|---|
| actions.alerts.(entry) | Alert entry | Object |
| actions.alerts.(entry).contactname | Name of alerted contact | String |
| actions.alerts.(entry).contactid | Identifier of alerted contact | String |
| actions.alerts.(entry).checkid | Identifier of check | String |
| actions.alerts.(entry).time | Time of alert generation. Format UNIX time | Integer |
| actions.alerts.(entry).via | Alert medium | String (email, sms, twitter, iphone, android) |
| actions.alerts.(entry).status | Alert status | String (sent, delivered, error, notdelivered, nocredits) |
| actions.alerts.(entry).messageshort | Short description of message | String |
| actions.alerts.(entry).messagefull | Full message body | String |
| actions.alerts.(entry).sentto | Target address, phone number etc | String |
| actions.alerts.(entry).charged | True if your account was charged for this message | Boolean |
Get a list of the latest alerts.
GET /api/2.0/actions?limit=2
{
"actions": {
"alerts": [
"contactname" : "John Doe",
"contactid" : 111250,
"checkid" : 241688,
"time" : 1292248276,
"via" : "sms",
"status" : "delivered",
"messageshort" : "up",
"messagefull" : "PingdomAlert UP: MyCheck (example.com) is UP again at 2010-12-13 14:50:54. Downtime: 12m.",
"sentto" : "46-555555",
"charged" : true
}, {
"contactname" : "John Doe",
"contactid" : 111250,
"checkid" : 241688,
"time" : 1292248254,
"via" : "email",
"status" : "sent",
"messageshort" : "up",
"messagefull" : "FROM:[email protected]\r\nTO:[email protected]\r\nSubject:UP alert: MyCheck (example.com) is UP\r\n\r\nPingdomAlert UP:\r\nMyCheck (example.com) is UP again at 2010-12-13 14:50:54, after 12m of downtime.",
"sentto" : "[email protected]",
"charged" : false
}
]
}
}
Returns a list of the latest root cause analysis results for a specified check.
/api/{version}/analysis/{checkid}
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| limit | Limits the number of returned results to the specified quantity. | Integer | no | 100 |
| offset | Offset for listing. (Requires limit.) | Integer | no | 0 |
| from | Return only results with timestamp of first test greater or equal to this value. Format is UNIX timestamp. | Integer | no | 0 |
| to | Return only results with timestamp of first test less or equal to this value. Format is UNIX timestamp. | Integer | no | Current timestamp |
| Attribute | Description | Type |
|---|---|---|
| analysis.(entry).id | Analysis id | Integer |
| analysis.(entry).timefirsttest | Time of test that initiated the confirmation test | Integer |
| analysis.(entry).timeconfirmtest | Time of the confirmation test that performed the error analysis | Integer |
Get a list of the latest analyses for check 161748
GET /api/2.0/analysis/161748
{
"analysis" : [ {
"id" : 28739021,
"timefirsttest" : 1290441826,
"timeconfirmtest" : 1290441865
}, {
"id" : 28737907,
"timefirsttest" : 1290440924,
"timeconfirmtest" : 1290440932
}, {
"id" : 28589686,
"timefirsttest" : 1290263024,
"timeconfirmtest" : 1290263059
}, {
"id" : 28063742,
"timefirsttest" : 1289647724,
"timeconfirmtest" : 1289647760
} ]
}
Returns the raw result for a specified error analysis. This data is primarily intended for internal use, but you might be interested in it as well. However, there is no real documentation for this data at the moment. In the future, we may add a new API method that provides a more user-friendly format.
/api/{version}/analysis/{checkid}/{analysisid}
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|
Returns a list overview of all checks.
/api/{version}/checks
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| limit | Limits the number of returned probes to the specified quantity. (Max value is 25000) | Integer | no | 25000 |
| offset | Offset for listing. (Requires limit.) | Integer | no | 0 |
| include_tags | Include tag list for each check. Tags can be marked as "a" or "u", for auto tagged or user tagged. | Boolean | no | false |
| tags | Tag list separated by commas. As an example "nginx,apache" would filter out all responses except those tagged nginx or apache. | String | no | N/A |
| Attribute | Description | Type |
|---|---|---|
| checks.(entry).id | Check identifier | Integer |
| checks.(entry).name | Check name | String |
| checks.(entry).type | Check type | String |
| checks.(entry).lasterrortime | Timestamp of last error (if any). Format is UNIX timestamp | Integer |
| checks.(entry).lasttesttime | Timestamp of last test (if any). Format is UNIX timestamp | Integer |
| checks.(entry).lastresponsetime | Response time (in milliseconds) of last test. | Integer |
| checks.(entry).status | Current status of check | String (up, down, unconfirmed_down, unknown, paused) |
| checks.(entry).resolution | How often should the check be tested? (minutes) | Integer |
| checks.(entry).hostname | Target host | String |
| checks.(entry).created | Creating time. Format is UNIX timestamp | Integer |
| checks.(entry).tags | List of tags for check | Array |
| checks.(entry).ipv6 | Use ipv6 instead of ipv4 | Boolean |
Get all checks
GET /api/2.0/checks
{
"checks": [
{
"hostname": "example.com",
"id": 85975,
"lasterrortime": 1297446423,
"lastresponsetime": 355,
"lasttesttime": 1300977363,
"name": "My check 1",
"resolution": 1,
"status": "up",
"type": "http",
"tags": [
{
"name": "apache",
"type": "a",
"count": 2
}
]
},
{
"hostname": "mydomain.com",
"id": 161748,
"lasterrortime": 1299194968,
"lastresponsetime": 1141,
"lasttesttime": 1300977268,
"name": "My check 2",
"resolution": 5,
"status": "up",
"type": "ping",
"tags": [
{
"name": "nginx",
"type": "u",
"count": 1
}
]
},
{
"hostname": "example.net",
"id": 208655,
"lasterrortime": 1300527997,
"lastresponsetime": 800,
"lasttesttime": 1300977337,
"name": "My check 3",
"resolution": 1,
"status": "down",
"type": "http",
"tags": [
{
"name": "apache",
"type": "a",
"count": 2
}
]
}
]
}
Returns a detailed description of a specified check.
/api/{version}/checks/{checkid}
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| check.id | Check identifier | Integer |
| check.name | Check name | String |
| check.hostname | Target host | String |
| check.status | Current check status | String (up, down, unconfirmed_down, unknown, paused) |
| check.resolution | How often should the check be tested? (minutes) | Integer |
| check.type | Contains one element representing the type of check and type-specific settings | Object |
| check.contactids.(entry) | Identifier of contact who should receive alerts | Integer |
| check.sendtoemail | Send alerts as email | Boolean |
| check.sendtosms | Send alerts as SMS | Boolean |
| check.sendtotwitter | Send alerts through Twitter | Boolean |
| check.sendtoiphone | Send alerts to iPhone | Boolean |
| check.sendtoandroid | Send alerts to Android | Boolean |
| check.sendnotificationwhendown | Send notification when down n times | Integer |
| check.notifyagainevery | Notify again every n result | Integer |
| check.notifywhenbackup | Notify when back up again | Boolean |
| check.lasterrortime | Timestamp of last error (if any). Format is UNIX timestamp | Integer |
| check.lasttesttime | Timestamp of last test (if any). Format is UNIX timestamp | Integer |
| check.lastresponsetime | Response time (in milliseconds) of last test. | Integer |
| check.created | Creating time. Format is UNIX timestamp | Integer |
| checks.(entry).ipv6 | Use ipv6 instead of ipv4 | Boolean |
| Attribute | Description | Type |
|---|---|---|
| check.type.http.url | Path to target on server | String |
| check.type.http.encryption | Connection encryption | Boolean |
| check.type.http.port | Target port | Integer |
| check.type.http.username | Username for target HTTP authentication | String |
| check.type.http.password | Password for target HTTP authentication | String |
| check.type.http.shouldcontain | Target site should contain this string | String |
| check.type.http.shouldnotcontain | Target site should NOT contain this string | String |
| check.type.http.postdata | Data that should be posted to the web page, for example submission data for a sign-up or login form. The data needs to be formatted in the same way as a web browser would send it to the web server | String |
| check.type.http.requestheaders.* | Custom HTTP header. Entry name should match header name | String |
| Attribute | Description | Type |
|---|---|---|
| check.type.httpcustom.url | Path to target XML file on server | String |
| check.type.httpcustom.encryption | Connection encryption | Boolean |
| check.type.httpcustom.port | Target port | Integer |
| check.type.http.username | Username for target HTTP authentication | String |
| check.type.http.password | Password for target HTTP authentication | String |
| check.type.httpcustom.additionalurls.(entry) | Full URL (including hostname) to target additional XML file. | String |
| Attribute | Description | Type |
|---|---|---|
| check.type.tcp.port | Target port | Integer |
| check.type.tcp.stringtosend | String to send | String |
| check.type.tcp.stringtoexpect | String to expect in response | String |
| Attribute | Description | Type |
|---|
| Attribute | Description | Type |
|---|---|---|
| check.type.dns.nameserver | DNS server to use | String |
| check.type.dns.expectedip | Expected IP | String |
| Attribute | Description | Type |
|---|---|---|
| check.type.udp.port | Target port | Integer |
| check.type.udp.stringtosend | String to send | String |
| check.type.udp.stringtoexpect | String to expect in response | String |
| Attribute | Description | Type |
|---|---|---|
| check.type.smtp.port | Target port | Integer |
| check.type.smtp.username | Username for target SMTP authentication | String |
| check.type.smtp.password | Password for target SMTP authentication | String |
| check.type.smtp.encryption | Connection encryption | Boolean |
| check.type.smtp.stringtoexpect | String to expect in response | String |
| Attribute | Description | Type |
|---|---|---|
| check.type.pop3.port | Target port | Integer |
| check.type.pop3.encryption | Connection encryption | Boolean |
| check.type.pop3.stringtoexpect | String to expect in response | String |
| Attribute | Description | Type |
|---|---|---|
| check.type.imap.port | Target port | Integer |
| check.type.imap.encryption | Connection encryption | Boolean |
| check.type.imap.stringtoexpect | String to expect in response | String |
Get detailed information about check 85975
GET /api/2.0/checks/85975
{
"check" : {
"id" : 85975,
"name" : "My check 7",
"resolution" : 1,
"sendtoemail" : false,
"sendtosms" : false,
"sendtotwitter" : false,
"sendtoiphone" : false,
"sendnotificationwhendown" : 0,
"notifyagainevery" : 0,
"notifywhenbackup" : false,
"created" : 1240394682,
"type" : {
"http" : {
"url" : "/",
"port" : 80,
"requestheaders" : {
"User-Agent" : "Pingdom.com_bot_version_1.4_(http://www.pingdom.com/)"
}
}
},
"hostname" : "s7.mydomain.com",
"status" : "up",
"lasterrortime" : 1293143467,
"lasttesttime" : 1294064823
}
}
Creates a new check with settings specified by provided parameters.
/api/{version}/checks
POST
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | Check name | String | yes | |
| host | Target host | String | yes | |
| type | Type of check | String (http, httpcustom, tcp, ping, dns, udp, smtp, pop3, imap) | yes | |
| paused | Paused | Boolean | no | false |
| resolution | Check resolution | Integer (1, 5, 15, 30, 60) | no | 5 |
| contactids | Contact identifiers. For example contactids=154325,465231,765871 | Comma separated Integers | no | |
| sendtoemail | Send alerts as email | Boolean | no | false |
| sendtosms | Send alerts as SMS | Boolean | no | false |
| sendtotwitter | Send alerts through Twitter | Boolean | no | false |
| sendtoiphone | Send alerts to iPhone | Boolean | no | false |
| sendtoandroid | Send alerts to Android | Boolean | no | false |
| sendnotificationwhendown | Send notification when down n times | Integer | no | 2 |
| notifyagainevery | Notify again every n result. 0 means that no extra notifications will be sent. | Integer | no | 0 |
| notifywhenbackup | Notify when back up again | Boolean | no | true |
| tags | Check tags | Comma separated strings | no | |
| ipv6 | Use ipv6 instead of ipv4, if an IP address is provided as host this will be overrided by the IP address version | Boolean | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| url | Target path on server | String | no | / |
| encryption | Connection encryption | Boolean | no | false |
| port | Target port | Integer | no | 80 |
| auth | Username and password for target HTTP authentication. Example: user:password | String | no | |
| shouldcontain | Target site should contain this string. | String | no | |
| shouldnotcontain | Target site should NOT contain this string. If shouldcontain is also set, this parameter is not allowed. | String | no | |
| postdata | Data that should be posted to the web page, for example submission data for a sign-up or login form. The data needs to be formatted in the same way as a web browser would send it to the web server | String | no | |
| requestheader{X} | Custom HTTP header name. Replace {X} with a number unique for each header argument. Example: requestheadername1=My-Header:CoolValue | String | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| url | Target path to XML file on server | String | yes | |
| encryption | Connection encryption | Boolean | no | false |
| port | Target port | Integer | no | 80 |
| auth | Username and password for target HTTP authentication. Example: user:password | String | no | |
| additionalurls | ;-separated list of addidional URLs with hostname included. Example: additionalurls=www.mysite.com;www.myothersite.com | String | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | yes | |
| stringtosend | String to send | String | no | |
| stringtoexpect | String to expect in response | String | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| expectedip | Expected ip | String | yes | |
| nameserver | Nameserver | String | yes |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | yes | |
| stringtosend | String to send | String | yes | |
| stringtoexpect | String to expect in response | String | yes |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | no | 25 |
| auth | Username and password for target SMTP authentication. Example: user:password | String | no | |
| stringtoexpect | String to expect in response | String | no | |
| encryption | Connection encryption | Boolean | no | false |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | no | 110 |
| stringtoexpect | String to expect in response | String | no | |
| encryption | Connection encryption | Boolean | no | false |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | no | 143 |
| stringtoexpect | String to expect in response | String | no | |
| encryption | Connection encryption | Boolean | no | false |
| Attribute | Description | Type |
|---|---|---|
| check.id | New check identifier | Integer |
| check.name | New check name | String |
Create a new HTTP check for www.mydomain.com with default settings
POST /api/2.0/checks
name=My+new+HTTP+check&type=http&host=www.mydomain.com
{
"check":{
"id":138631,
"name":"My new HTTP check"
}
}
Create a new SMTP check for smtp.mymailserver.com with SSL/TLS encryption, provided user/password, 15 minutes check resolution, with SMS and email alerts to contacts 123456 and 789012 after 1 down result
POST /api/2.0/checks
name=My+new+SMTP+check&type=smtp&resolution=15&sendtoemail=true&sendtosms=true&sendnotificationwhendown=1&contactids=123456,789012&host=smtp.mymailserver.com&
auth=myuser%3Amypassword&encryption=true
{
"check":{
"id":138632,
"name":"My new SMTP check"
}
}
Modify settings for a check. The provided settings will overwrite previous values. Settings not provided will stay the same as before the update. To clear an existing value, provide an empty value. Please note that you cannot change the type of a check once it has been created.
/api/{version}/checks/{checkid}
PUT
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | Check name | String | no | |
| host | Target host | String | no | |
| paused | Paused | Boolean | no | |
| resolution | Check resolution | Integer (1, 5, 15, 30, 60) | no | |
| contactids | Contact identifiers. For example contactids=154325,465231,765871 | Comma separated Integers | no | |
| sendtoemail | Send alerts as email | Boolean | no | |
| sendtosms | Send alerts as SMS | Boolean | no | |
| sendtotwitter | Send alerts through Twitter | Boolean | no | |
| sendtoiphone | Send alerts to iPhone | Boolean | no | |
| sendtoandroid | Send alerts to Android | Boolean | no | |
| sendnotificationwhendown | Send notification when down n times | Integer | no | |
| notifyagainevery | Notify again every n result. 0 means that no extra notifications will be sent. | Integer | no | |
| notifywhenbackup | Notify when back up again | Boolean | no | |
| tags | Check tags. Overwrites previous tags for check To remove all tags from a check, use an empty value | Comma separated strings | no | |
| addtags | Check tags to add in addition to current check tags | Comma separated strings | no | |
| ipv6 | Use ipv6 instead of ipv4, if an IP address is provided as host this will be overrided by the IP address version | Boolean | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| url | Target path on server | String | no | |
| encryption | Connection encryption | Boolean | no | |
| port | Target port | Integer | no | |
| auth | Username and password for target HTTP authentication. Example: user:password | String | no | |
| shouldcontain | Target site should contain this string | String | no | |
| shouldnotcontain | Target site should NOT contain this string. If shouldcontain is also set, this parameter is not allowed. | String | no | |
| postdata | Data that should be posted to the web page, for example submission data for a sign-up or login form. The data needs to be formatted in the same way as a web browser would send it to the web server | String | no | |
| requestheader{X} | Custom HTTP header name. Replace {X} with a number unique for each header argument. Example: requestheadername1=My-Header:CoolValue | String | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| url | Target path to XML file on server | String | no | |
| encryption | Connection encryption | Boolean | no | |
| port | Target port | Integer | no | |
| auth | Username and password for target HTTP authentication. Example: user:password | String | no | |
| additionalurls | ;-separated list of addidional URLs with hostname included. Example: additionalurls=www.mysite.com;www.myothersite.com | String | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | no | |
| stringtosend | String to send | String | no | |
| stringtoexpect | String to expect in response | String | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| expectedip | Expected ip | String | no | |
| nameserver | Nameserver | String | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | no | |
| stringtosend | String to send | String | no | |
| stringtoexpect | String to expect in response | String | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | no | |
| auth | Username and password for target SMTP authentication. Example: user:password | String | no | |
| stringtoexpect | String to expect in response | String | no | |
| encryption | Connection encryption | Boolean | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | no | 110 |
| stringtoexpect | String to expect in response | String | no | |
| encryption | Connection encryption | Boolean | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | no | 143 |
| stringtoexpect | String to expect in response | String | no | |
| encryption | Connection encryption | Boolean | no |
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
Change user/password and resolution on SMTP check 138632
PUT /api/2.0/checks/138632
auth=newuser%3Anewpassword&resolution=30
{
"message":"Modification of check was successful!"
}
Pause check 138632
PUT /api/2.0/checks/138632
paused=true
{
"message":"Modification of check was successful!"
}
Pause or change resolution for multiple checks in one bulk call.
/api/{version}/checks
PUT
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| paused | Paused | Boolean | no | |
| resolution | Check resolution | Integer (1, 5, 15, 30, 60) | no | |
| checkids | Comma-separated list of identifiers for checks to be modified. Invalid check identifiers will be ignored. | String | no | All checks |
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
Pause all checks
PUT /api/2.0/checks
paused=true
{
"message" : "Modification of 4 checks was successful!"
}
Resume all checks
PUT /api/2.0/checks
paused=false
{
"message" : "Modification of 4 checks was successful!"
}
Deletes a check. THIS METHOD IS IRREVERSIBLE! You will lose all collected data. Be careful!
/api/{version}/checks/{checkid}
DELETE
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
Permanently delete check 134536
DELETE /api/2.0/checks/134536
{
"message":"Deletion of check was successful!"
}
Deletes a list of checks. THIS METHOD IS IRREVERSIBLE! You will lose all collected data. Be careful!
/api/{version}/checks
DELETE
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| delcheckids | Comma-separated list of identifiers for checks to be deleted. | String | yes |
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
Permanently delete checks 134536, 134539 and 134551
DELETE /api/2.0/checks
delcheckids=134536,134539,134551
{
"message":"Deletion of checks was successful!"
}
Returns a list of all contacts.
/api/{version}/contacts
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| limit | Limits the number of returned contacts to the specified quantity. | Integer | no | 100 |
| offset | Offset for listing. (Requires limit.) | Integer | no | 0 |
| Attribute | Description | Type |
|---|---|---|
| contacts.(entry).id | Contact identifier | Integer |
| contacts.(entry).name | Contact name | String |
| contacts.(entry).email | Contact email | String |
| contacts.(entry).cellphone | Contact cellphone | String |
| contacts.(entry).countryiso | Cellphone country ISO code | String |
| contacts.(entry).defaultsmsprovider | Default SMS provider | String |
| contacts.(entry).directtwitter | Send Twitter messages as Direct Messages | Boolean |
| contacts.(entry).twitteruser | Twitter username | String |
| contacts.(entry).iphonetokens.(entry) | iPhone token | String |
| contacts.(entry).androidtokens.(entry) | Android token | String |
| contacts.(entry).paused | True if contact is paused | Boolean |
GET /api/2.0/contacts
{
"contacts" : [ {
"id" : 111250,
"name" : "John Doe",
"email" : "[email protected]",
"cellphone" : "46-5555555",
"countryiso" : "SE",
"defaultsmsprovider" : "clickatell",
"directtwitter" : false,
"paused" : false
} ]
}
Create a new contact.
/api/{version}/contacts
POST
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | Name | String | yes | |
| String | no | |||
| cellphone | Cellphone number, without the country code part. In some countries you are supposed to exclude leading zeroes. (Requires countrycode and countryiso) | String | no | |
| countrycode | Cellphone country code (Requires cellphone and countryiso) | String | no | |
| countryiso | Cellphone country ISO code. For example: US (USA), GB (Britain) or SE (Sweden) (Requires cellphone and countrycode) | String | no | |
| defaultsmsprovider | Default SMS provider | String (clickatell, bulksms, esendex, cellsynt) | no | clickatell |
| directtwitter | Send twitter messages as Direct Messages | Boolean | no | true |
| twitteruser | Twitter user | String | no |
| Attribute | Description | Type |
|---|---|---|
| contact.id | New contact identifier | Integer |
| contact.name | New contact name | String |
POST /api/2.0/contacts
cellphone=705555555&countrycode=46&countryiso=se&email=danny%40dannysdomain.com&name=Danny+Boy
{
"contact":{
"id":786111,
"name":"Danny Boy"
}
}
Modify a contact.
/api/{version}/contacts/{contactid}
PUT
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | Name | String | no | |
| String | no | |||
| cellphone | Cellphone number, without the country code part. In some countries you are supposed to exclude leading zeroes. (Requires countrycode and countryiso) | String | no | |
| countrycode | Cellphone country code (Requires cellphone and countryiso) | String | no | |
| countryiso | Cellphone country ISO code. For example: US (USA), GB (Britain) or SE (Sweden) (Requires cellphone and countrycode) | String | no | |
| defaultsmsprovider | Default SMS provider | String (clickatell, bulksms, esendex, cellsynt) | no | |
| directtwitter | Send twitter messages as Direct Messages | Boolean | no | |
| twitteruser | Twitter user | String | no | |
| paused | Pause contact | Boolean | no |
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
Change email on contact 786111
PUT /api/2.0/contacts/786111
email=newmail%40dannysdomain.com
{
"message":"Modification of contact was successful!"
}
Modifies a list of contacts.
/api/{version}/contacts
PUT
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| contactids | Comma-separated list of identifiers for contacts to be modified. | String | yes | |
| paused | Pause contacts | Boolean | yes |
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
Pause contacts 786111, 786115 and 786365
PUT /api/2.0/contacts
contactids=786111,786115,786365&paused=true
{
"message":"Modification of contacts was successful!"
}
Deletes a contact.
/api/{version}/contacts/{contactid}
DELETE
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
Permanently delete contact 657234
DELETE /api/2.0/contacts/657234
{
"message":"Deletion of contact was successful!"
}
Deletes a list of contacts.
/api/{version}/contacts
DELETE
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| delcontactids | Comma-separated list of identifiers for contacts to be deleted. | String | yes |
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
Permanently delete contact 657234, 657235 and 657256
DELETE /api/2.0/contacts
delcheckids=657234,657235,657256
{
"message":"Deletion of contacts was successful!"
}
Returns information about remaining checks, SMS credits and SMS auto-refill status.
/api/{version}/credits
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| credits.checklimit | Total number of check slots on this account | Integer |
| credits.availablechecks | Free check slots available for new checks | Integer |
| credits.availablesms | SMS credits remaining on this account | Integer |
| credits.availablesmstests | SMS provider tests remaining on this account | Integer |
| credits.autofillsms | Auto fill SMS | Boolean |
Get credits list
GET /api/2.0/credits
{
"credits": {
"autofillsms": false,
"availablechecks": 46,
"availablesms": 98,
"availablesmstests": 86,
"checklimit": 50
}
}
Returns a list of all Pingdom probe servers for Uptime and Transaction checks.
/api/{version}/probes
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| limit | Limits the number of returned probes to the specified quantity. | Integer | no | |
| offset | Offset for listing. (Requires limit.) | Integer | no | 0 |
| onlyactive | Return only active probes. | Boolean | no | false |
| includedeleted | Include old probes that are no longer in use | Boolean | no | false |
| Attribute | Description | Type |
|---|---|---|
| probes | A list of probes | Array |
| probes.(entry) | Probe body | Object |
| probes.(entry).id | Unique probe id | Integer |
| probes.(entry).country | Country | String |
| probes.(entry).city | City | String |
| probes.(entry).name | Name | String |
| probes.(entry).active | Is the probe currently active? | Boolean |
| probes.(entry).hostname | DNS name | String |
| probes.(entry).ip | IP address | String |
| probes.(entry).countryiso | Country ISO code | String |
Get all (existing) probes
GET /api/2.0/probes
{
"probes":[
{
"id":1,
"country":"United Kingdom",
"city":"Manchester",
"name":"Manchester, UK",
"active":true,
"hostname":"s424.pingdom.com",
"ip":"212.84.74.156",
"countryiso":"GB"
},
{
"id":2,
"country":"United States",
"city":"New York",
"name":"New York, NY",
"active":true,
"hostname":"s413.pingdom.com",
"ip":"70.32.40.2"
"countryiso":"US"
},
{
"id":3,
"country":"Denmark",
"city":"Copenhagen",
"name":"Copenhagen, Denmark",
"active":true,
"hostname":"s416.pingdom.com",
"ip":"82.103.128.63"
"countryiso":"DK"
}
]
}
Get a reference of regions, timezones and date/time/number formats and their identifiers.
/api/{version}/reference
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| regions.id | Region identifier | Integer |
| regions.description | Region description | String |
| regions.countryid | Corresponding country identifier | Integer |
| regions.datetimeformatid | Corresponding datetimeformat identifier | Integer |
| regions.numberformatid | Corresponding numberformat identifier | Integer |
| regions.timezoneid | Corresponding timezone identifier | Integer |
| timezones.id | Time zone identifier | Integer |
| timezones.description | Time zone description | String |
| datetimeformats.id | Date/time format identifier | Integer |
| datetimeformats.description | Date/time format description | String |
| numberformats.id | Number format identifier | Integer |
| numberformats.description | Number format description | String |
| countries.id | Country id | Integer |
| countries.iso | Country ISO code | String |
| countries.name | Country name | String |
| phonecodes.countryid | Country id (Can be mapped against countries.id) | Integer |
| phonecodes.name | Country name | String |
| phonecodes.phonecode | Area phone code | String |
GET /api/2.0/reference
{
"regions" : [ {
"id" : 2,
"description" : "United States (Alaska)"
}, {
"id" : 1,
"description" : "United States (Hawaii)"
}, {
"id" : 3,
"description" : "United States (Pacific Time)"
}, {
"id" : 4,
"description" : "United States (Mountain Time)"
}, {
"id" : 5,
"description" : "United States (Central Time)"
}, {
"id" : 6,
"description" : "United States (Eastern Time)"
}, {
"id" : 7,
"description" : "Sweden"
}, {
"id" : 8,
"description" : "United Kingdom"
}, {
"id" : 9,
"description" : "India"
}, {
"id" : 10,
"description" : "Canada (Pacific Time)"
}, {
"id" : 11,
"description" : "Canada (Mountain Time)"
}, {
"id" : 12,
"description" : "Canada (Central Time)"
}, {
"id" : 13,
"description" : "Canada (Eastern Time)"
}, {
"id" : 14,
"description" : "Canada (Atlantic Time)"
}, {
"id" : 15,
"description" : "Canada (Newfoundland)"
}, {
"id" : 16,
"description" : "China"
}, {
"id" : 17,
"description" : "Australia (Adelaide)"
}, {
"id" : 18,
"description" : "Australia (Canberra, Melbourne, Sydney)"
}, {
"id" : 19,
"description" : "Turkey"
}, {
"id" : 20,
"description" : "Spain"
}, {
"id" : 21,
"description" : "Brazil (Eastern Time)"
}, {
"id" : 22,
"description" : "Brazil (Atlantic Time)"
}, {
"id" : 23,
"description" : "Brazil (Brazil, Buenos Aires, Georgetown)"
}, {
"id" : 24,
"description" : "Brazil (Mid-Atlantic)"
}, {
"id" : 25,
"description" : "Indonesia (Bangkok, Hanoi, Jakarta)"
}, {
"id" : 26,
"description" : "Indonesia (Beijing, Perth, Singapore, Hong Kong)"
}, {
"id" : 27,
"description" : "Indonesia (Tokyo, Seoul, Osaka)"
}, {
"id" : 28,
"description" : "Romania"
}, {
"id" : 29,
"description" : "Mexico (Pacific Time)"
}, {
"id" : 30,
"description" : "Mexico (Mountain Time)"
}, {
"id" : 31,
"description" : "Mexico (Central Time)"
}, {
"id" : 32,
"description" : "Bulgaria"
}, {
"id" : 33,
"description" : "Portugal (Azores)"
}, {
"id" : 34,
"description" : "Portugal (Western Europe Time, London, Lisbon)"
}, {
"id" : 35,
"description" : "Egypt"
}, {
"id" : 36,
"description" : "Italy"
}, {
"id" : 37,
"description" : "Pakistan"
}, {
"id" : 38,
"description" : "France"
}, {
"id" : 39,
"description" : "New Zealand"
}, {
"id" : 40,
"description" : "Australia (Lord Howe Island)"
}, {
"id" : 41,
"description" : "New Zealand (Chatham Islands)"
}, {
"id" : 42,
"description" : "Germany"
}, {
"id" : 43,
"description" : "Saudi Arabia"
}, {
"id" : 44,
"description" : "Australia (Perth)"
} ],
"timezones" : [ {
"id" : 1,
"description" : "(GMT -12:00) Eniwetok, Kwajalein"
}, {
"id" : 2,
"description" : "(GMT -11:00) Midway Island, Samoa"
}, {
"id" : 3,
"description" : "(GMT -10:00) Hawaii"
}, {
"id" : 4,
"description" : "(GMT -9:00) Alaska"
}, {
"id" : 5,
"description" : "(GMT -8:00) Pacific Time (US & Canada)"
}, {
"id" : 6,
"description" : "(GMT -7:00) Mountain Time (US & Canada)"
}, {
"id" : 7,
"description" : "(GMT -6:00) Central Time (US & Can.), Mexico"
}, {
"id" : 8,
"description" : "(GMT -5:00) Eastern Time (US & Can.)"
}, {
"id" : 9,
"description" : "(GMT -4:00) Atlantic Time (Can.)"
}, {
"id" : 10,
"description" : "(GMT -3:30) Newfoundland"
}, {
"id" : 11,
"description" : "(GMT -3:00) Brazil, Buenos Aires, Georgetown"
}, {
"id" : 12,
"description" : "(GMT -2:00) Mid-Atlantic"
}, {
"id" : 13,
"description" : "(GMT -1:00 hour) Azores"
}, {
"id" : 14,
"description" : "(GMT) Western Europe Time, London, Lisbon"
}, {
"id" : 15,
"description" : "(GMT +1:00 hour) Brussels, Copenhagen, Madrid"
}, {
"id" : 16,
"description" : "(GMT +2:00) Athens, Cairo"
}, {
"id" : 17,
"description" : "(GMT +3:00) Baghdad, Moscow, Riyadh"
}, {
"id" : 18,
"description" : "(GMT +3:30) Tehran"
}, {
"id" : 19,
"description" : "(GMT +4:00) Abu Dhabi, Muscat"
}, {
"id" : 20,
"description" : "(GMT +4:30) Kabul"
}, {
"id" : 21,
"description" : "(GMT +5:00) Islamabad, Karachi"
}, {
"id" : 22,
"description" : "(GMT +5:30) Bombay, Calcutta, Colombo, New Delhi"
}, {
"id" : 23,
"description" : "(GMT +6:00) Almaty, Dhaka"
}, {
"id" : 24,
"description" : "(GMT +7:00) Bangkok, Hanoi, Jakarta"
}, {
"id" : 25,
"description" : "(GMT +8:00) Beijing, Perth, Singapore, Hong Kong"
}, {
"id" : 26,
"description" : "(GMT +9:00) Tokyo, Seoul, Osaka"
}, {
"id" : 27,
"description" : "(GMT +9:30) Adelaide"
}, {
"id" : 28,
"description" : "(GMT +10:00) Canbera, Melbourne, Sydney"
}, {
"id" : 29,
"description" : "(GMT +11:00) Solomon Isl., New Caledonia"
}, {
"id" : 30,
"description" : "(GMT +12:00) Auckland, Fiji, Kamchatka"
}, {
"id" : 32,
"description" : "(GMT +10:30) Lord Howe Island"
}, {
"id" : 33,
"description" : "(GMT +12:45) Chatham Islands"
}, {
"id" : 34,
"description" : "(GMT +10:00) Brisbane"
}, {
"id" : 35,
"description" : "(GMT +13:00) New Zealand Daylight Time, Tonga"
}, {
"id" : 36,
"description" : "(GMT) Reykjavik"
}, {
"id" : 37,
"description" : "(GMT +2:00) South African Standard Time"
}, {
"id" : 38,
"description" : "(GMT -4:30) Caracas"
}, {
"id" : 39,
"description" : "(GMT -6:00) Central America, El Salvador"
} ],
"datetimeformats" : [ {
"id" : 1,
"description" : "07/31/2006 02:45:05pm"
}, {
"id" : 2,
"description" : "31/07/2006 02:45:05pm"
}, {
"id" : 3,
"description" : "31/07/2006 14:45:05"
}, {
"id" : 4,
"description" : "2006-07-31 14:45:05"
}, {
"id" : 5,
"description" : "31.07.2006. 14:45:05"
}, {
"id" : 6,
"description" : "31/07/2006 14h45m05"
}, {
"id" : 7,
"description" : "31-07-2006 02:45:05pm"
}, {
"id" : 8,
"description" : "31-07-2006 14:45:05"
} ],
"numberformats" : [ {
"id" : 1,
"description" : "123,456,789.00"
}, {
"id" : 2,
"description" : "123 456 789.00"
}, {
"id" : 3,
"description" : "123456789.00"
}, {
"id" : 4,
"description" : "123.456.789,00"
}, {
"id" : 5,
"description" : "123 456 789,00"
}, {
"id" : 6,
"description" : "123456789,00"
} ]
}
Returns a list of email report subscriptions.
/api/{version}/reports.email
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| subscriptions.(entry).id | Subscription identifier | Integer |
| subscriptions.(entry).name | Subscription name | String |
| subscriptions.(entry).type | Subscription type | String |
| subscriptions.(entry).checkid | Check identifier for check subscriptions | String |
| subscriptions.(entry).frequency | Report frequency | String |
| subscriptions.(entry).additionalemails.(entry) | Additional receiving email | String |
| subscriptions.(entry).contactids.(entry) | Identifier for receiving contact | String |
GET /api/2.0/reports.email
{
"subscriptions" : [ {
"id" : 114979,
"name" : "My subscription",
"type" : "overview",
"frequency" : "monthly",
"contactids" : [ 111250 ]
} ]
}
Creates a new email report.
/api/{version}/reports.email
POST
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | Name | String | yes | |
| checkid | Check identifier. If omitted, this will be an overview report | Integer | no | |
| frequency | Report frequency | String (monthly, weekly, daily) | no | monthly |
| contactids | Comma separated list of receiving contact identifiers | String | no | |
| additionalemails | Comma separated list of additional receiving emails | String | no |
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
POST /api/2.0/reports.email
name=My+subscription&frequency=weekly&contactids=123456,134253
{
"message":"Subscription added"
}
Modify an email report.
/api/{version}/reports.email/{reportid}
PUT
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | Name | String | no | |
| checkid | Check identifier. If omitted, this will be an overview report | Integer | no | |
| frequency | Report frequency | String (monthly, weekly, daily) | no | |
| contactids | Comma separated list of receiving contact identifiers | String | no | |
| additionalemails | Comma separated list of additional receiving emails | String | no |
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
PUT /api/2.0/reports.email/634253
name=My+subscription+modified&frequency=monthly&contactids=123456
{
"message":"Subscription modified"
}
Delete an email report.
/api/{version}/reports.email/{reportid}
DELETE
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
DELETE /api/2.0/reports.email/634253
{
"message":"Subscription deleted"
}
Returns a list of public (web-based) reports.
/api/{version}/reports.public
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| public.(entry).checkid | Check identifier | Integer |
| public.(entry).checkname | Check name | String |
| public.(entry).reporturl | URL to report | String |
GET /api/2.0/reports.public
{
"public" : [ {
"checkid" : 85975,
"checkname" : "ubuntu packages",
"reporturl" : "http://www.pingdom.com/reports/rwknj2rkd39h/check_overview/?name=ubuntu+packages"
} ]
}
Activate public report for a specified check.
/api/{version}/reports.public/{checkid}
PUT
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
PUT /api/2.0/reports.public/123456
{
"message":"Check published"
}
Deactivate public report for a specified check.
/api/{version}/reports.public/{checkid}
DELETE
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
DELETE /api/2.0/reports.public/123456
{
"message":"Check unpublished"
}
Returns a list of shared reports (banners).
/api/{version}/reports.shared
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| shared.banners.(entry).id | Banner identifier | Integer |
| shared.banners.(entry).name | Banner name | String |
| shared.banners.(entry).checkid | Check identifier | Integer |
| shared.banners.(entry).auto | Automatic period activated? | Boolean |
| shared.banners.(entry).type | Banner type | String (response, uptime) |
| shared.banners.(entry).url | Banner URL | String |
| shared.banners.(entry).fromyear | Period start: year | Integer |
| shared.banners.(entry).frommonth | Period start: month | Integer |
| shared.banners.(entry).fromday | Period start: day | Integer |
| shared.banners.(entry).toyear | Period end: year | Integer |
| shared.banners.(entry).tomonth | Period end: month | Integer |
| shared.banners.(entry).today | Period end: day | Integer |
GET /api/2.0/reports.shared
{
"shared" : {
"banners" : [ {
"id" : "9338512f",
"name" : "mydomain.com",
"checkid" : 241688,
"auto" : true,
"type" : "uptime",
"url" : "http://share.pingdom.com/banners/9338512f"
}, {
"id" : "476a37ba",
"name" : "myotherdomain.com",
"checkid" : 241688,
"auto" : true,
"type" : "uptime",
"url" : "http://share.pingdom.com/banners/476a37ba"
} ]
}
}
Create a shared report (banner).
/api/{version}/reports.shared
POST
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| sharedtype | Shared report type. For now, only "banner" is valid | String (banner) | yes | |
| checkid | Identifier of target check | Integer | yes | |
| auto | Automatic period (If false, requires: fromyear, frommonth, fromday, toyear, tomonth, today) | Boolean | no | true |
| fromyear | Period start: year | Integer | no | |
| frommonth | Period start: month | Integer | no | |
| fromday | Period start: day | Integer | no | |
| toyear | Period end: year | Integer | no | |
| tomonth | Period end: month | Integer | no | |
| today | Period end: day | Integer | no | |
| type | Banner type | String (uptime, response) | no | uptime |
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
POST /api/2.0/reports.shared
sharedtype=banner&checkid=123456
{
"message":"Banner created"
}
Delete a shared report (banner).
/api/{version}/reports.shared/{reportid}
DELETE
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| message | Message | String |
DELETE /api/2.0/reports.shared/476a37ba
{
"message":"Banner deleted"
}
Return a list of raw test results for a specified check
/api/{version}/results/{checkid}
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| to | End of period. Format is UNIX timestamp | Integer | no | current time |
| from | Start of period. Format is UNIX timestamp | Integer | no | 1 day prior to 'to' |
| probes | Filter to only show results from a list of probes. Format is a comma separated list of probe identifiers | String | no | all probes |
| status | Filter to only show results with specified statuses. Format is a comma separated list of (down, up, unconfirmed, unknown) | String | no | all statuses |
| limit | Number of results to show (Will be set to 1000 if the provided value is greater than 1000) | Integer | no | 1000 |
| offset | Number of results to skip (Max value is 43200) | Integer | no | 0 |
| includeanalysis | Attach available root cause analysis identifiers to corresponding results | Boolean | no | false |
| maxresponse | Maximum response time (ms). If set, specified interval must not be larger than 31 days. | Integer | no | |
| minresponse | Minimum response time (ms). If set, specified interval must not be larger than 31 days. | Integer | no |
| Attribute | Description | Type |
|---|---|---|
| results.(entry).probeid | Probe identifier | Integer |
| results.(entry).time | Time when test was performed. Format is UNIX timestamp | Integer |
| results.(entry).status | Result status | String (up, down, unconfirmed_down, unknown) |
| results.(entry).responsetime | Response time (in milliseconds) (Will be 0 if no response was received) | Integer |
| results.(entry).statusdesc | Short status description | String |
| results.(entry).statusdesclong | Long status description | String |
| results.(entry).analysisid | Analysis identifier | Integer |
| activeprobes | For your convinience, a list of used probes that produced the showed results | Array |
| activeprobes.(entry) | Probe identifier | Integer |
Get the 5 latest results for check 85975
GET /api/2.0/results/85975?limit=5
{
"results" : [ {
"probeid" : 33,
"time" : 1294235764,
"status" : "up",
"responsetime" : 91,
"statusdesc" : "OK",
"statusdesclong" : "OK"
}, {
"probeid" : 34,
"time" : 1294235703,
"status" : "up",
"responsetime" : 442,
"statusdesc" : "OK",
"statusdesclong" : "OK"
}, {
"probeid" : 35,
"time" : 1294235643,
"status" : "up",
"responsetime" : 187,
"statusdesc" : "OK",
"statusdesclong" : "OK"
}, {
"probeid" : 36,
"time" : 1294235583,
"status" : "up",
"responsetime" : 403,
"statusdesc" : "OK",
"statusdesclong" : "OK"
}, {
"probeid" : 37,
"time" : 1294235523,
"status" : "up",
"responsetime" : 111,
"statusdesc" : "OK",
"statusdesclong" : "OK"
} ],
"activeprobes" : [ 33, 34, 35, 36, 37 ]
}
Get the current time of the API server.
/api/{version}/servertime
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| servertime | Current server time. Format is UNIX timestamp | Integer |
GET /api/2.0/servertime
{
"servertime" : 1294237910
}
Returns all account-specific settings.
/api/{version}/settings
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Attribute | Description | Type |
|---|---|---|
| settings.firstname | First name | String |
| settings.lastname | Last name | String |
| settings.company | Company | String |
| settings.email | String | |
| settings.phone | Phone | String |
| settings.phonecountryiso | Phone country ISO code | String |
| settings.cellphone | Cellphone | String |
| settings.cellphonecountryiso | Cellphone country ISO code | String |
| settings.address | Address line 1 | String |
| settings.address2 | Address line 2 | String |
| settings.zip | Zip, postal code or equivalent | String |
| settings.location | City / location | String |
| settings.state | State or equivalent | String |
| settings.autologout | Enable auto-logout | Boolean |
| settings.country | Country | Object |
| settings.country.name | Country name | String |
| settings.country.iso | Country ISO-code | String |
| settings.country.countryid | Country identifier, see the Reference resource | Integer |
| settings.vatcode | For certain EU countries, VAT-code | String |
| settings.region | Region | String |
| settings.regionid | Region identifier, see the Reference resource | Integer |
| settings.accountcreated | Account creation timestamp, UNIX time format | Integer |
| settings.timezone | Time zone | Object |
| settings.timezone.id | Time zone name | String |
| settings.timezone.description | Time zone description | String |
| settings.timezone.timezoneid | Corresponding timezone identifier, see the Reference resource | Integer |
| settings.dateformat | Date format | String |
| settings.timeformat | Time format | String |
| settings.datetimeformatid | Time/date format identifier, see the Reference resource | Integer |
| settings.numberformat | Number format | String |
| settings.numberexample | Example of number presentation | String |
| settings.numberformatid | Number format identifier, see the Reference resource | Integer |
| settings.publicreports | Public reports settings | String |
| settings.publicreports.customdesign | Use custom design for public reports | Boolean |
| settings.publicreports.textcolor | Custom text color | String |
| settings.publicreports.backgroundcolor | Background color | String |
| settings.publicreports.logourl | URL to custom logotype | String |
| settings.publicreports.months | Number of months to show | String |
| settings.publicreports.showoverview | Enable overview | Boolean |
| settings.publicreports.customdomain | Custom domain | String |
| settings.publicreportscode | URL code | String |
| settings.settingssaved | True if the user has saved initial settings in the control panel | Boolean |
GET /api/2.0/settings
{
"settings" : {
"firstname" : "John",
"lastname" : "Smith",
"company" : "Pingdom",
"email" : "[email protected]",
"phone" : "",
"cellphone" : "46-555555555",
"address" : "Pingdom Street 1",
"address2" : "",
"zip" : "55555",
"location" : "Pingdom City",
"state" : "",
"autologout" : false,
"country" : {
"name" : "Sweden",
"iso" : "SE"
},
"region" : "Sweden",
"timezone" : {
"id" : "CET",
"description" : "(GMT +1:00 hour) Brussels, Copenhagen, Madrid"
},
"dateformat" : "%Y-%m-%d",
"timeformat" : "%H:%M:%S",
"numberformat" : ", ",
"numberexample" : "123 456 789,00"
}
}
Modify account-specific settings.
/api/{version}/settings
PUT
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| firstname | First name | String | no | |
| lastname | Last name | String | no | |
| company | Company | String | no | |
| Email (Please note that your email is used for authentication purposes such as using this API or logging into the Pingdom Panel) | String | no | ||
| cellphone | Cellphone (without country code) (Requires cellcountrycode and cellcountryiso) | String | no | |
| cellcountrycode | Cellphone country code, for example 1 (USA) or 46 (Sweden) | Integer | no | |
| cellcountryiso | Cellphone country ISO code, for example US (USA) or SE (Sweden) | String | no | |
| phone | Phone (without country code) (Requires phonecountrycode and phonecountryiso) | String | no | |
| phonecountrycode | Phone country code, for example 1 (USA) or 46 (Sweden) | Integer | no | |
| phonecountryiso | Phone country ISO code, for example US (USA) or SE (Sweden) | String | no | |
| address | Address line 1 | String | no | |
| address2 | Address line 2 | String | no | |
| zip | Zip, postal code or equivalent | String | no | |
| location | City / location | String | no | |
| state | State, province or equivalent | String | no | |
| countryiso | Country ISO code, for example US (USA) or SE (Sweden) | String | no | |
| vatcode | For certain EU countries, VAT-code. Example: SE123456789 | String | no | |
| autologout | Enable auto-logout | Boolean | no | |
| regionid | Region identifier, for localization purposes. 0 for "Custom"/none. See the API resource "Reference" for more information | Integer | no | |
| timezoneid | Time zone identifier. See the API resource "Reference" for more information | Integer | no | |
| datetimeformatid | Date/time format identifier. See the API resource "Reference" for more information | Integer | no | |
| numberformatid | Number format identifier. See the API resource "Reference" for more information | Integer | no | |
| pubrcustomdesign | Use custom design for public reports | Boolean | no | |
| pubrtextcolor | Public reports, custom text color (Example: FEFFFE or 99CC00) | String | no | |
| pubrbackgroundcolor | Public reports, background color (Example: FEFFFE or 99CC00) | String | no | |
| pubrlogourl | Public reports, URL to custom logotype. This parameter is currently disabled for public use. (Example: stats.pingdom.com/images/logo.png) | String | no | |
| pubrmonths | Public reports, number of months to show | String (none, all, 3) | no | |
| pubrshowoverview | Public reports, enable overview | Boolean | no | |
| pubrcustomdomain | Public reports, custom domain. Must be a DNS CNAME with target stats.pingdom.com | Boolean | no |
| Attribute | Description | Type |
|---|
Change company name to Pingdom and state to Neverland
PUT /api/2.0/settings
company=Pingdom&state=Neverland
{
"message":"Settings updated successfully"
}
Get the average time / uptime value for a specified check and time period.
/api/{version}/summary.average/{checkid}
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| from | Start time of period. Format is UNIX timestamp | Integer | no | 0 |
| to | End time of period. Format is UNIX timestamp | Integer | no | current time |
| probes | Filter to only use results from a list of probes. Format is a comma separated list of probe identifiers | String | no | all probes |
| includeuptime | Include uptime information | Boolean | no | false |
| bycountry | Split response times into country groups | Boolean | no | false |
| byprobe | Split response times into probe groups | Boolean | no | false |
| Attribute | Description | Type |
|---|---|---|
| summary.responsetime.from | Start time of period | Integer |
| summary.responsetime.to | End time of period | Integer |
| summary.responsetime.avgresponse | Total average response time in milliseconds | Integer |
| summary.responsetime.(entry).countryiso | Country group ISO code | Integer |
| summary.responsetime.(entry).probeid | Probe group probe identifier | Integer |
| summary.responsetime.(entry).avgresponse | Group average response time in milliseconds | Integer |
| summary.status.totalup | Total uptime in seconds (Please note that the accuracy of this value is depending on your check resolution) | Integer |
| summary.status.totaldown | Total downtime in seconds (Please note that the accuracy of this value is depending on your check resolution) | Integer |
| summary.status.totalunknown | Total unknown/unmonitored/paused in seconds (Please note that the accuracy of this value is depending on your check resolution. Also note that time before the check was created counts as unknown) | Integer |
GET /api/2.0/summary.average/85975
includeuptime=true
{
"summary" : {
"responsetime" : {
"from" : 0,
"to" : 1294245352,
"avgresponse" : 458
},
"status" : {
"totalup" : 53072286,
"totaldown" : 771879,
"totalunknown" : 1240401138
}
}
}
GET /api/2.0/summary.average/85975
bycountry=true
{
"summary" : {
"responsetime" : {
"from" : 0,
"to" : 1294245226,
"avgresponse" : [ {
"countryiso" : "SE",
"avgresponse" : 250
}, {
"countryiso" : "US",
"avgresponse" : 650
}, {
"countryiso" : "GB",
"avgresponse" : 129
}, {
"countryiso" : "CA",
"avgresponse" : 442
}, {
"countryiso" : "NL",
"avgresponse" : 162
}, {
"countryiso" : "DE",
"avgresponse" : 200
}, {
"countryiso" : "DK",
"avgresponse" : 229
}, {
"countryiso" : "FR",
"avgresponse" : 204
}, {
"countryiso" : "ES",
"avgresponse" : 285
} ]
}
}
}
Returns the average response time for each hour of the day (0-23) for a specific check over a selected time period. I.e. it shows you what an average day looks like during that time period.
/api/{version}/summary.hoursofday/{checkid}
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| from | Start time of period. Format is UNIX timestamp | Integer | no | One week earlier than "to" |
| to | End time of period. Format is UNIX timestamp | Integer | no | Current time |
| probes | Filter to only use results from a list of probes. Format is a comma separated list of probe identifiers | String | no | all probes |
| uselocaltime | If true, use the user's local time zone for results (from and to parameters should still be specified in UTC). If false, use UTC for results. | Boolean | no | false |
| Attribute | Description | Type |
|---|---|---|
| hoursofday.(entry).hour | Hour of day (0-23). Please note that if data is missing for an individual hour, it's entry will not be included in the result. | Integer |
| hoursofday.(entry).avgresponse | Average response time (in milliseconds) for this hour of the day | Integer |
Get averages for the last week
GET /api/2.0/summary.hoursofday/85975
{
"hoursofday" : [ {
"hour" : 0,
"avgresponse" : 259
}, {
"hour" : 1,
"avgresponse" : 299
}, {
"hour" : 2,
"avgresponse" : 259
}, {
"hour" : 3,
"avgresponse" : 327
}, {
"hour" : 4,
"avgresponse" : 302
},
"hour" : 5,
"avgresponse" : 376
},
"hour" : 6,
"avgresponse" : 256
},
"hour" : 7,
"avgresponse" : 262
},
"hour" : 8,
"avgresponse" : 328
},
"hour" : 9,
"avgresponse" : 335
},
"hour" : 10,
"avgresponse" : 276
}, {
"hour" : 11,
"avgresponse" : 291
}, {
"hour" : 12,
"avgresponse" : 287
}, {
"hour" : 13,
"avgresponse" : 267
}, {
"hour" : 14,
"avgresponse" : 276
}, {
"hour" : 15,
"avgresponse" : 266
}, {
"hour" : 16,
"avgresponse" : 326
}, {
"hour" : 17,
"avgresponse" : 292
}, {
"hour" : 18,
"avgresponse" : 301
}, {
"hour" : 19,
"avgresponse" : 270
}, {
"hour" : 20,
"avgresponse" : 282
}, {
"hour" : 21,
"avgresponse" : 262
}, {
"hour" : 22,
"avgresponse" : 270
}, {
"hour" : 23,
"avgresponse" : 253
} ]
}
Get a list of status changes for a specified check and time period. If order is speficied to descending, the list is ordered by newest first. (Default is ordered by oldest first.)
/api/{version}/summary.outage/{checkid}
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| from | Start time of period. Format is UNIX timestamp | Integer | no | One week earlier than to |
| to | End time of period. Format is UNIX timestamp | Integer | no | current time |
| order | Sorting order of outages. Ascending or descending. | String (asc,desc) | no | asc |
| Attribute | Description | Type |
|---|---|---|
| summary.states.(entry).status | Interval status | String (up, down, unknown) |
| summary.states.(entry).timefrom | Interval start. Format UNIX timestamp | Integer |
| summary.states.(entry).timeto | Interval end. Format UNIX timestamp | Integer |
GET /api/2.0/summary.outage/85975
{
"summary" : {
"states" : [ {
"status" : "up",
"timefrom" : 1293143523,
"timeto" : 1294180263
}, {
"status" : "down",
"timefrom" : 1294180263,
"timeto" : 1294180323
}, {
"status" : "up",
"timefrom" : 1294180323,
"timeto" : 1294223466
}, {
"status" : "down",
"timefrom" : 1294223466,
"timeto" : 1294223523
}, {
"status" : "up",
"timefrom" : 1294223523,
"timeto" : 1294228503
}, {
"status" : "down",
"timefrom" : 1294228503,
"timeto" : 1294228563
}, {
"status" : "up",
"timefrom" : 1294228563,
"timeto" : 1294228623
}, {
"status" : "down",
"timefrom" : 1294228623,
"timeto" : 1294228743
}, {
"status" : "up",
"timefrom" : 1294228743,
"timeto" : 1294228803
}, {
"status" : "down",
"timefrom" : 1294228803,
"timeto" : 1294228987
}, {
"status" : "up",
"timefrom" : 1294228987,
"timeto" : 1294229047
}, {
"status" : "down",
"timefrom" : 1294229047,
"timeto" : 1294229583
}, {
"status" : "up",
"timefrom" : 1294229583,
"timeto" : 1294229643
}, {
"status" : "down",
"timefrom" : 1294229643,
"timeto" : 1294230063
}, {
"status" : "up",
"timefrom" : 1294230063,
"timeto" : 1294389243
} ]
}
}
For a given interval in time, return a list of sub intervals with the given resolution. Useful for generating graphs. A sub interval may be a week, a day or an hour depending on the choosen resolution.
/api/{version}/summary.performance/{checkid}
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| from | Start time of period. Format is UNIX timestamp | Integer | no | 10 intervals earlier than to |
| to | End time of period. Format is UNIX timestamp | Integer | no | current time |
| resolution | Interval size | String (hour, day, week) | no | hour |
| includeuptime | Include uptime information. | Boolean | no | false |
| probes | Filter to only use results from a list of probes. Format is a comma separated list of probe identifiers. Can not be used if includeuptime is set to true. Also note that this can cause intervals to be omitted, since there may be no results from the desired probes in them. | String | no | all probes |
| order | Sorting order of sub intervals. Ascending or descending. | String (asc,desc) | no | asc |
| Attribute | Description | Type |
|---|---|---|
| summary.hours.(entry).starttime | Hour interval start. Format UNIX timestamp | Integer |
| summary.hours.(entry).avgresponse | Average response time for this interval in milliseconds | Integer |
| summary.hours.(entry).uptime | Total uptime for this interval in seconds | Integer |
| summary.hours.(entry).downtime | Total downtime for this interval in seconds | Integer |
| summary.hours.(entry).unmonitored | Total unmonitored time for this interval in seconds | Integer |
| summary.days.(entry).starttime | Day interval start. Format UNIX timestamp | Integer |
| summary.days.(entry).avgresponse | Average response time for this interval in milliseconds | Integer |
| summary.days.(entry).uptime | Total uptime for this interval in seconds | Integer |
| summary.days.(entry).downtime | Total downtime for this interval in seconds | Integer |
| summary.days.(entry).unmonitored | Total unmonitored time for this interval in seconds | Integer |
| summary.weeks.(entry).starttime | Week interval start. Format UNIX timestamp | Integer |
| summary.weeks.(entry).avgresponse | Average response time for this interval in milliseconds | Integer |
| summary.weeks.(entry).uptime | Total uptime for this interval in seconds | Integer |
| summary.weeks.(entry).downtime | Total downtime for this interval in seconds | Integer |
| summary.weeks.(entry).unmonitored | Total unmonitored time for this interval in seconds | Integer |
GET /api/2.0/summary.performance/85975?includeuptime=true&resolution=week
{
"summary" : {
"weeks" : [ {
"starttime" : 1287957600,
"avgresponse" : 468,
"uptime" : 608400,
"downtime" : 0,
"unmonitored" : 0
}, {
"starttime" : 1288566000,
"avgresponse" : 467,
"uptime" : 604620,
"downtime" : 180,
"unmonitored" : 0
}, {
"starttime" : 1289170800,
"avgresponse" : 440,
"uptime" : 604680,
"downtime" : 120,
"unmonitored" : 0
}, {
"starttime" : 1289775600,
"avgresponse" : 451,
"uptime" : 604680,
"downtime" : 120,
"unmonitored" : 0
}, {
"starttime" : 1290380400,
"avgresponse" : 456,
"uptime" : 604680,
"downtime" : 120,
"unmonitored" : 0
}, {
"starttime" : 1290985200,
"avgresponse" : 465,
"uptime" : 604496,
"downtime" : 304,
"unmonitored" : 0
}, {
"starttime" : 1291590000,
"avgresponse" : 489,
"uptime" : 604610,
"downtime" : 190,
"unmonitored" : 0
}, {
"starttime" : 1292194800,
"avgresponse" : 466,
"uptime" : 604800,
"downtime" : 0,
"unmonitored" : 0
}, {
"starttime" : 1292799600,
"avgresponse" : 452,
"uptime" : 604680,
"downtime" : 120,
"unmonitored" : 0
}, {
"starttime" : 1293404400,
"avgresponse" : 447,
"uptime" : 604800,
"downtime" : 0,
"unmonitored" : 0
}, {
"starttime" : 1294009200,
"avgresponse" : 465,
"uptime" : 382511,
"downtime" : 1437,
"unmonitored" : 0
} ]
}
}
Get a list of probes that performed tests for a specified check during a specified period.
/api/{version}/summary.probes/{checkid}
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| from | Start time of period. Format is UNIX timestamp | Integer | yes | |
| to | End time of period. Format is UNIX timestamp | Integer | no | current time |
| Attribute | Description | Type |
|---|---|---|
| probes.(entry) | Probe identifier | Integer |
GET /api/2.0/summary.probes/85975?from=1294393564&to=1294394816
{
"probes" : [ 43, 42, 41, 40, 39, 37, 36, 35, 34, 33, 32, 31, 30, 29, 28, 27, 24, 23, 22, 21 ]
}
Performs a single test using a specified Pingdom probe against a specified target. Please note that this method is meant to be used sparingly, not to set up your own monitoring solution.
/api/{version}/single
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| host | Target host | String | yes | |
| type | Type of test | String (http, httpcustom, tcp, ping, dns, udp, smtp, pop3, imap) | yes | |
| probeid | Probe identifier | Integer | no | A random probe |
| ipv6 | Use ipv6 instead of ipv4 | Boolean | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| url | Target path on server | String | no | / |
| encryption | Connection encryption | Boolean | no | false |
| port | Target port | Integer | no | 80 |
| auth | Username and password for target HTTP authentication. Example: user:password | String | no | |
| shouldcontain | Target site should contain this string | String | no | |
| shouldnotcontain | Target site should NOT contain this string | String | no | |
| postdata | Data that should be posted to the web page, for example submission data for a sign-up or login form. The data needs to be formatted in the same way as a web browser would send it to the web server | String | no | |
| requestheader{X} | Custom HTTP header name. Replace {X} with a number unique for each header argument. Example: requestheader1=My-Header:CoolValue | String | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| url | Target path to XML file on server | String | yes | |
| encryption | Connection encryption | Boolean | no | false |
| port | Target port | Integer | no | 80 |
| auth | Username and password for target HTTP authentication. Example: user:password | String | no | |
| additionalurls | ;-separated list of addidional URLs with hostname included. Example: additionalurls=www.mysite.com;www.myothersite.com | String | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | yes | |
| stringtosend | String to send | String | no | |
| stringtoexpect | String to expect in response | String | no |
| Parameter name | Description | Type | Mandatory | Default |
|---|
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| expectedip | Expected ip | String | yes | |
| nameserver | Nameserver | String | yes |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | yes | |
| stringtosend | String to send | String | yes | |
| stringtoexpect | String to expect in response | String | yes |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | no | 25 |
| auth | Username and password for target SMTP authentication. Example: user:password | String | no | |
| stringtoexpect | String to expect in response | String | no | |
| encryption | Connection encryption | Boolean | no | false |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | no | 110 |
| stringtoexpect | String to expect in response | String | no | |
| encryption | Connection encryption | Boolean | no | false |
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| port | Target port | Integer | no | 143 |
| stringtoexpect | String to expect in response | String | no | |
| encryption | Connection encryption | Boolean | no | false |
| Attribute | Description | Type |
|---|---|---|
| result.status | Test result status | String (up, down) |
| result.responsetime | Response time in milliseconds | Integer |
| result.statusdesc | Short status description | String |
| result.statusdesclong | Long status description | String |
| result.probeid | Probe identifier | Integer |
| result.probedesc | Probe description | String |
GET /api/2.0/single?host=pingdom.com&type=http&probeid=17
{
"result" : {
"status" : "up",
"responsetime" : 73,
"statusdesc" : "OK",
"statusdesclong" : "OK",
"probeid" : 17,
"probedesc" : "Stockholm, Sweden"
}
}
Perform a traceroute to a specified target from a specified Pingdom probe.
/api/{version}/traceroute
GET
200
| Parameter name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| host | Target host | String | yes | |
| probeid | Probe identifier | Integer | no | A random probe |
| Attribute | Description | Type |
|---|---|---|
| traceroute.result | Traceroute output | String |
| traceroute.probeid | Probe identifier | Integer |
| traceroute.probedescription | Probe description | String |
GET api/2.0/traceroute?host=pingdom.com&probeid=23
{
"traceroute" : {
"result" : "traceroute to pingdom.com (83.140.19.136), 30 hops max, 40 byte packets\n 1 67.192.120.130 (67.192.120.130) 4.803 ms 5.000 ms 5.202 ms\n 2 67.192.56.2 (67.192.56.2) 0.332 ms 0.352 ms 0.431 ms\n 3 vlan905.edge4.dfw1.rackspace.com (67.192.56.228) 0.384 ms 0.444 ms 0.497 ms\n 4 12.87.41.177 (12.87.41.177) 1.926 ms 1.983 ms *\n 5 cr1.dlstx.ip.att.net (12.122.139.122) 3.696 ms 3.725 ms 3.741 ms\n 6 dlstx01jt.ip.att.net (12.122.80.41) 1.792 ms 1.817 ms 1.840 ms\n 7 192.205.34.82 (192.205.34.82) 1.668 ms 1.828 ms 192.205.34.142 (192.205.34.142) 1.722 ms\n 8 RIX-TELECOM-AB.TenGigabitEthernet9-3.ar2.ANR3.gblx.net (64.208.169.138) 147.221 ms 146.710 ms 146.473 ms\n 9 po41-20g-r86.cr1-r85.hy-sto.se.p80.net (82.96.1.162) 146.334 ms 146.347 ms 146.776 ms\n10 83.140.54.18.cust.port80.se (83.140.54.18) 146.741 ms 146.311 ms 146.283 ms\n11 83.140.19.136 (83.140.19.136) 146.789 ms 146.710 ms 146.795 ms\n",
"probeid" : 23,
"probedescription" : "Dallas 4, TX"
}
}
