Guides 8fe4b5282ea5be04e5fb2155000bc7a89f8c033132bfca760699bdba2a0571d2

Pingdom API

Index

Welcome to the Pingdom API!

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

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

Multi-User Authentication

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 foo@example.com. The account on which you want to perform the API request is bar@example.com. You would authenticate as foo@example.com, with the Account‑Email header set to bar@example.com.

Request
    > GET /checks HTTP/1.1
    > Host: api.pingdom.com
    > Authentication: Zm9vQGV4YW1wbGUuY29tOnBhc3N3b3Jk
    > App-Key: 1234567890abcdef1234567890abcdef
    > Account-Email: bar@example.com
Response
    < HTTP/1.1 200 OK
    < Content-Length: 13
    < Content-Type: application/json

    {"checks":[]}

Server Address

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.

Providing Parameters

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.

HTTP/1.1 Status Code Definitions

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.

JSON Responses

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.

Limits

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:

  • Req-Limit-Short
  • Req-Limit-Long

An example of the values of these headers:

  • Req-Limit-Short: Remaining: 394 Time until reset: 3589
  • Req-Limit-Long: Remaining: 71994 Time until reset: 2591989

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.

gzip

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

Best Practices

Use caching

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.

Send your user credentials in a preemptive manner

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.

Use common sense

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.

The Internet is unreliable

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.

PHP Code Example

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

Code
<?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, "johndoe@example.com: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";
}

?>
Example output:
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);

Rest Requests

Below you can find descriptions and examples for all methods.

Resource: Actions

Method: Get Actions (Alerts) List
Description

Returns a list of actions (alerts) that have been generated for your account.

URL Syntax

/api/{version}/actions

HTTP Method

GET

Successful HTTP Response

200

Parameters
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
Response Attributes
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
Examples

Get a list of the latest alerts.

Request

GET /api/2.0/actions?limit=2

Response
{
        "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:alert@pingdom.com\r\nTO:john@example.com\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" : "john@example.com",
                "charged" : false
              }
            ]
        }
    }

Back to top

Resource: Analysis

Method: Get Root Cause Analysis Results List
Description

Returns a list of the latest root cause analysis results for a specified check.

URL Syntax

/api/{version}/analysis/{checkid}

HTTP Method

GET

Successful HTTP Response

200

Parameters
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
Response Attributes
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
Examples

Get a list of the latest analyses for check 161748

Request

GET /api/2.0/analysis/161748

Response
{
      "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
      } ]
    }

Back to top

Method: Get Raw Analysis Results
Description

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.

URL Syntax

/api/{version}/analysis/{checkid}/{analysisid}

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
Examples

Back to top

Resource: Checks

Method: Get Check List
Description

Returns a list overview of all checks.

URL Syntax

/api/{version}/checks

HTTP Method

GET

Successful HTTP Response

200

Parameters
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
Response Attributes
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
Examples

Get all checks

Request

GET /api/2.0/checks

Response
{
        "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
                    }
                ]
            }
        ]
    }

Back to top

Method: Get Detailed Check Information
Description

Returns a detailed description of a specified check.

URL Syntax

/api/{version}/checks/{checkid}

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
Response Attributes
General attributes
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
HTTP attributes
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
HTTP Custom attributes
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
TCP attributes
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
Ping attributes
Attribute Description Type
DNS attributes
Attribute Description Type
check.type.dns.nameserver DNS server to use String
check.type.dns.expectedip Expected IP String
UDP attributes
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
SMTP attributes
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
POP3 attributes
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
IMAP attributes
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
Examples

Get detailed information about check 85975

Request

GET /api/2.0/checks/85975

Response
{
      "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
      }
    }

Back to top

Method: Create New Check
Description

Creates a new check with settings specified by provided parameters.

URL Syntax

/api/{version}/checks

HTTP Method

POST

Successful HTTP Response

200

Parameters
General parameters for ALL new checks
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
Type-specific parameters for HTTP checks
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
Type-specific parameters for HTTP Custom checks
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
Type-specific parameters for TCP checks
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
Type-specific parameters for Ping checks
Parameter name Description Type Mandatory Default
Type-specific parameters for DNS checks
Parameter name Description Type Mandatory Default
expectedip Expected ip String yes
nameserver Nameserver String yes
Type-specific parameters for UDP checks
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
Type-specific parameters for SMTP checks
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
Type-specific parameters for POP3 checks
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
Type-specific parameters for IMAP checks
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
Response Attributes
Attribute Description Type
check.id New check identifier Integer
check.name New check name String
Examples

Create a new HTTP check for www.mydomain.com with default settings

Request

POST /api/2.0/checks

body:

name=My+new+HTTP+check&type=http&host=www.mydomain.com

Response
{
       "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

Request

POST /api/2.0/checks

body:

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

Response
{
       "check":{
          "id":138632,
          "name":"My new SMTP check"
       }
    }

Back to top

Method: Modify Check
Description

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.

URL Syntax

/api/{version}/checks/{checkid}

HTTP Method

PUT

Successful HTTP Response

200

Parameters
General parameters for ALL checks
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
Type-specific parameters for HTTP checks
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
Type-specific parameters for HTTP Custom checks
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
Type-specific parameters for TCP checks
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
Type-specific parameters for Ping checks
Parameter name Description Type Mandatory Default
Type-specific parameters for DNS checks
Parameter name Description Type Mandatory Default
expectedip Expected ip String no
nameserver Nameserver String no
Type-specific parameters for UDP checks
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
Type-specific parameters for SMTP checks
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
Type-specific parameters for POP3 checks
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
Type-specific parameters for IMAP checks
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
Response Attributes
Attribute Description Type
message Message String
Examples

Change user/password and resolution on SMTP check 138632

Request

PUT /api/2.0/checks/138632

body:

auth=newuser%3Anewpassword&resolution=30

Response
{
       "message":"Modification of check was successful!"
    }

Pause check 138632

Request

PUT /api/2.0/checks/138632

body:

paused=true

Response
{
       "message":"Modification of check was successful!"
    }

Back to top

Method: Modify Multiple Checks
Description

Pause or change resolution for multiple checks in one bulk call.

URL Syntax

/api/{version}/checks

HTTP Method

PUT

Successful HTTP Response

200

Parameters
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
Response Attributes
Attribute Description Type
message Message String
Examples

Pause all checks

Request

PUT /api/2.0/checks

body:

paused=true

Response
{
      "message" : "Modification of 4 checks was successful!"
    }

Resume all checks

Request

PUT /api/2.0/checks

body:

paused=false

Response
{
      "message" : "Modification of 4 checks was successful!"
    }

Back to top

Method: Delete Check
Description

Deletes a check. THIS METHOD IS IRREVERSIBLE! You will lose all collected data. Be careful!

URL Syntax

/api/{version}/checks/{checkid}

HTTP Method

DELETE

Successful HTTP Response

200

Parameters
None
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
message Message String
Examples

Permanently delete check 134536

Request

DELETE /api/2.0/checks/134536

Response
{
       "message":"Deletion of check was successful!"
    }

Back to top

Method: Delete Multiple Checks
Description

Deletes a list of checks. THIS METHOD IS IRREVERSIBLE! You will lose all collected data. Be careful!

URL Syntax

/api/{version}/checks

HTTP Method

DELETE

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
delcheckids Comma-separated list of identifiers for checks to be deleted. String yes
Response Attributes
Attribute Description Type
message Message String
Examples

Permanently delete checks 134536, 134539 and 134551

Request

DELETE /api/2.0/checks

body:

delcheckids=134536,134539,134551

Response
{
       "message":"Deletion of checks was successful!"
    }

Back to top

Resource: Contacts

Method: Get Contacts List
Description

Returns a list of all contacts.

URL Syntax

/api/{version}/contacts

HTTP Method

GET

Successful HTTP Response

200

Parameters
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
Response Attributes
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
Examples
Request

GET /api/2.0/contacts

Response
{
      "contacts" : [ {
        "id" : 111250,
        "name" : "John Doe",
        "email" : "john@johnsdomain.com",
        "cellphone" : "46-5555555",
        "countryiso" : "SE",
        "defaultsmsprovider" : "clickatell",
        "directtwitter" : false,
        "paused" : false
      } ]
    }

Back to top

Method: Create Contact
Description

Create a new contact.

URL Syntax

/api/{version}/contacts

HTTP Method

POST

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
name Name String yes
email Email 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
Response Attributes
Attribute Description Type
contact.id New contact identifier Integer
contact.name New contact name String
Examples
Request

POST /api/2.0/contacts

body:

cellphone=705555555&countrycode=46&countryiso=se&email=danny%40dannysdomain.com&name=Danny+Boy

Response
{
       "contact":{
          "id":786111,
          "name":"Danny Boy"
       }
    }

Back to top

Method: Modify Contact
Description

Modify a contact.

URL Syntax

/api/{version}/contacts/{contactid}

HTTP Method

PUT

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
name Name String no
email Email 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
Response Attributes
Attribute Description Type
message Message String
Examples

Change email on contact 786111

Request

PUT /api/2.0/contacts/786111

body:

email=newmail%40dannysdomain.com

Response
{
       "message":"Modification of contact was successful!"
    }

Back to top

Method: Modify Multiple Contacts
Description

Modifies a list of contacts.

URL Syntax

/api/{version}/contacts

HTTP Method

PUT

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
contactids Comma-separated list of identifiers for contacts to be modified. String yes
paused Pause contacts Boolean yes
Response Attributes
Attribute Description Type
message Message String
Examples

Pause contacts 786111, 786115 and 786365

Request

PUT /api/2.0/contacts

body:

contactids=786111,786115,786365&paused=true

Response
{
       "message":"Modification of contacts was successful!"
    }

Back to top

Method: Delete Contact
Description

Deletes a contact.

URL Syntax

/api/{version}/contacts/{contactid}

HTTP Method

DELETE

Successful HTTP Response

200

Parameters
None
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
message Message String
Examples

Permanently delete contact 657234

Request

DELETE /api/2.0/contacts/657234

Response
{
       "message":"Deletion of contact was successful!"
    }

Back to top

Method: Delete Multiple Contacts
Description

Deletes a list of contacts.

URL Syntax

/api/{version}/contacts

HTTP Method

DELETE

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
delcontactids Comma-separated list of identifiers for contacts to be deleted. String yes
Response Attributes
Attribute Description Type
message Message String
Examples

Permanently delete contact 657234, 657235 and 657256

Request

DELETE /api/2.0/contacts

body:

delcheckids=657234,657235,657256

Response
{
       "message":"Deletion of contacts was successful!"
    }

Back to top

Resource: Credits

Method: Get Credits List
Description

Returns information about remaining checks, SMS credits and SMS auto-refill status.

URL Syntax

/api/{version}/credits

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
Response Attributes
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
Examples

Get credits list

Request

GET /api/2.0/credits

Response
{
        "credits": {
            "autofillsms": false,
            "availablechecks": 46,
            "availablesms": 98,
            "availablesmstests": 86,
            "checklimit": 50
        }
    }

Back to top

Resource: Probes

Method: Get Probe Server List
Description

Returns a list of all Pingdom probe servers.

URL Syntax

/api/{version}/probes

HTTP Method

GET

Successful HTTP Response

200

Parameters
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
Response Attributes
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
Examples

Get all (existing) probes

Request

GET /api/2.0/probes

Response
{
       "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"
          }
       ]
    }

Back to top

Resource: Reference

Method: Get Reference
Description

Get a reference of regions, timezones and date/time/number formats and their identifiers.

URL Syntax

/api/{version}/reference

HTTP Method

GET

Successful HTTP Response

200

Parameters
None
Parameter name Description Type Mandatory Default
Response Attributes
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
Examples
Request

GET /api/2.0/reference

Response
{
      "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 &amp; Canada)"
      }, {
        "id" : 6,
        "description" : "(GMT -7:00) Mountain Time (US &amp; Canada)"
      }, {
        "id" : 7,
        "description" : "(GMT -6:00) Central Time (US &amp; Can.), Mexico"
      }, {
        "id" : 8,
        "description" : "(GMT -5:00) Eastern Time (US &amp; 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"
      } ]
    }

Back to top

Resource: Reports.email

Method: Get Email Report Subscription List
Description

Returns a list of email report subscriptions.

URL Syntax

/api/{version}/reports.email

HTTP Method

GET

Successful HTTP Response

200

Parameters
None
Parameter name Description Type Mandatory Default
Response Attributes
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
Examples
Request

GET /api/2.0/reports.email

Response
{
      "subscriptions" : [ {
        "id" : 114979,
        "name" : "My subscription",
        "type" : "overview",
        "frequency" : "monthly",
        "contactids" : [ 111250 ]
      } ]
    }

Back to top

Method: Create Email Report
Description

Creates a new email report.

URL Syntax

/api/{version}/reports.email

HTTP Method

POST

Successful HTTP Response

200

Parameters
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
Response Attributes
Attribute Description Type
message Message String
Examples
Request

POST /api/2.0/reports.email

body:

name=My+subscription&frequency=weekly&contactids=123456,134253

Response
{
       "message":"Subscription added"
    }

Back to top

Method: Modify Email Report
Description

Modify an email report.

URL Syntax

/api/{version}/reports.email/{reportid}

HTTP Method

PUT

Successful HTTP Response

200

Parameters
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
Response Attributes
Attribute Description Type
message Message String
Examples
Request

PUT /api/2.0/reports.email/634253

body:

name=My+subscription+modified&frequency=monthly&contactids=123456

Response
{
       "message":"Subscription modified"
    }

Back to top

Method: Delete Email Report
Description

Delete an email report.

URL Syntax

/api/{version}/reports.email/{reportid}

HTTP Method

DELETE

Successful HTTP Response

200

Parameters
None
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
message Message String
Examples
Request

DELETE /api/2.0/reports.email/634253

Response
{
       "message":"Subscription deleted"
    }

Back to top

Resource: Reports.public

Method: Get Public Report List
Description

Returns a list of public (web-based) reports.

URL Syntax

/api/{version}/reports.public

HTTP Method

GET

Successful HTTP Response

200

Parameters
None
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
public.(entry).checkid Check identifier Integer
public.(entry).checkname Check name String
public.(entry).reporturl URL to report String
Examples
Request

GET /api/2.0/reports.public

Response
{
      "public" : [ {
        "checkid" : 85975,
        "checkname" : "ubuntu packages",
        "reporturl" : "http://www.pingdom.com/reports/rwknj2rkd39h/check_overview/?name=ubuntu+packages"
      } ]
    }

Back to top

Method: Publish Public Report
Description

Activate public report for a specified check.

URL Syntax

/api/{version}/reports.public/{checkid}

HTTP Method

PUT

Successful HTTP Response

200

Parameters
None
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
message Message String
Examples
Request

PUT /api/2.0/reports.public/123456

Response
{
        "message":"Check published"
    }

Back to top

Method: Withdraw Public Report
Description

Deactivate public report for a specified check.

URL Syntax

/api/{version}/reports.public/{checkid}

HTTP Method

DELETE

Successful HTTP Response

200

Parameters
None
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
message Message String
Examples
Request

DELETE /api/2.0/reports.public/123456

Response
{
        "message":"Check unpublished"
    }

Back to top

Resource: Reports.shared

Method: Get Shared Reports (Banners) List
Description

Returns a list of shared reports (banners).

URL Syntax

/api/{version}/reports.shared

HTTP Method

GET

Successful HTTP Response

200

Parameters
None
Parameter name Description Type Mandatory Default
Response Attributes
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
Examples
Request

GET /api/2.0/reports.shared

Response
{
      "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"
        } ]
      }
    }

Back to top

Method: Create Shared Report (Banner)
Description

Create a shared report (banner).

URL Syntax

/api/{version}/reports.shared

HTTP Method

POST

Successful HTTP Response

200

Parameters
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
Response Attributes
Attribute Description Type
message Message String
Examples
Request

POST /api/2.0/reports.shared

body:

sharedtype=banner&checkid=123456

Response
{
        "message":"Banner created"
    }

Back to top

Method: Delete Shared Report (Banner)
Description

Delete a shared report (banner).

URL Syntax

/api/{version}/reports.shared/{reportid}

HTTP Method

DELETE

Successful HTTP Response

200

Parameters
None
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
message Message String
Examples
Request

DELETE /api/2.0/reports.shared/476a37ba

Response
{
       "message":"Banner deleted"
    }

Back to top

Resource: Results

Method: Get Raw Check Results
Description

Return a list of raw test results for a specified check

URL Syntax

/api/{version}/results/{checkid}

HTTP Method

GET

Successful HTTP Response

200

Parameters
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
Response Attributes
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
Examples

Get the 5 latest results for check 85975

Request

GET /api/2.0/results/85975?limit=5

Response
{
      "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 ]
      }

Back to top

Resource: Servertime

Method: Get Current Server Time
Description

Get the current time of the API server.

URL Syntax

/api/{version}/servertime

HTTP Method

GET

Successful HTTP Response

200

Parameters
None
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
servertime Current server time. Format is UNIX timestamp Integer
Examples
Request

GET /api/2.0/servertime

Response
{
      "servertime" : 1294237910
    }

Back to top

Resource: Settings

Method: Get Account Settings
Description

Returns all account-specific settings.

URL Syntax

/api/{version}/settings

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
settings.firstname First name String
settings.lastname Last name String
settings.company Company String
settings.email 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
Examples
Request

GET /api/2.0/settings

Response
{
      "settings" : {
      "firstname" : "John",
      "lastname" : "Smith",
      "company" : "Pingdom",
      "email" : "johndoe@pingdom.com",
      "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"
      }
      }

Back to top

Method: Modify Account Settings
Description

Modify account-specific settings.

URL Syntax

/api/{version}/settings

HTTP Method

PUT

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
firstname First name String no
lastname Last name String no
company Company String no
email 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
Response Attributes
Attribute Description Type
Examples

Change company name to Pingdom and state to Neverland

Request

PUT /api/2.0/settings

body:

company=Pingdom&state=Neverland

Response
{
      "message":"Settings updated successfully"
      }

Back to top

Resource: Summary.average

Method: Get A Response Time / Uptime Average
Description

Get the average time / uptime value for a specified check and time period.

URL Syntax

/api/{version}/summary.average/{checkid}

HTTP Method

GET

Successful HTTP Response

200

Parameters
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
Response Attributes
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
Examples
Request

GET /api/2.0/summary.average/85975

body:

includeuptime=true

Response
{
      "summary" : {
        "responsetime" : {
          "from" : 0,
          "to" : 1294245352,
          "avgresponse" : 458
        },
        "status" : {
          "totalup" : 53072286,
          "totaldown" : 771879,
          "totalunknown" : 1240401138
        }
      }
    }
Request

GET /api/2.0/summary.average/85975

body:

bycountry=true

Response
{
      "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
          } ]
        }
      }
    }

Back to top

Resource: Summary.hoursofday

Method: Get Response Time Averages For Each Hour Of The Day
Description

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.

URL Syntax

/api/{version}/summary.hoursofday/{checkid}

HTTP Method

GET

Successful HTTP Response

200

Parameters
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
Response Attributes
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
Examples

Get averages for the last week

Request

GET /api/2.0/summary.hoursofday/85975

Response
{
      "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
      } ]
    }

Back to top

Resource: Summary.outage

Method: Get List of Outages
Description

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

URL Syntax

/api/{version}/summary.outage/{checkid}

HTTP Method

GET

Successful HTTP Response

200

Parameters
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
Response Attributes
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
Examples
Request

GET /api/2.0/summary.outage/85975

Response
{
      "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
        } ]
      }
    }

Back to top

Resource: Summary.performance

Method: Get Intervals of Average Response Time and Uptime During a Given Interval
Description

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.

URL Syntax

/api/{version}/summary.performance/{checkid}

HTTP Method

GET

Successful HTTP Response

200

Parameters
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
Response Attributes
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
Examples
Request

GET /api/2.0/summary.performance/85975?includeuptime=true&resolution=week

Response
{
      "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
        } ]
      }
    }

Back to top

Resource: Summary.probes

Method: Get Active Probes For A Period
Description

Get a list of probes that performed tests for a specified check during a specified period.

URL Syntax

/api/{version}/summary.probes/{checkid}

HTTP Method

GET

Successful HTTP Response

200

Parameters
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
Response Attributes
Attribute Description Type
probes.(entry) Probe identifier Integer
Examples
Request

GET /api/2.0/summary.probes/85975?from=1294393564&to=1294394816

Response
{
      "probes" : [ 43, 42, 41, 40, 39, 37, 36, 35, 34, 33, 32, 31, 30, 29, 28, 27, 24, 23, 22, 21 ]
    }

Back to top

Resource: Single

Method: Make A Single Test
Description

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.

URL Syntax

/api/{version}/single

HTTP Method

GET

Successful HTTP Response

200

Parameters
General parameters for ALL single tests
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
Type-specific parameters for HTTP tests
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
Type-specific parameters for HTTP Custom tests
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
Type-specific parameters for TCP tests
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
Type-specific parameters for Ping tests
Parameter name Description Type Mandatory Default
Type-specific parameters for DNS tests
Parameter name Description Type Mandatory Default
expectedip Expected ip String yes
nameserver Nameserver String yes
Type-specific parameters for UDP tests
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
Type-specific parameters for SMTP tests
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
Type-specific parameters for POP3 tests
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
Type-specific parameters for IMAP tests
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
Response Attributes
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
Examples
Request

GET /api/2.0/single?host=pingdom.com&type=http&probeid=17

Response
{
      "result" : {
        "status" : "up",
        "responsetime" : 73,
        "statusdesc" : "OK",
        "statusdesclong" : "OK",
        "probeid" : 17,
        "probedesc" : "Stockholm, Sweden"
      }
    }

Back to top

Resource: Traceroute

Method: Make A Traceroute
Description

Perform a traceroute to a specified target from a specified Pingdom probe.

URL Syntax

/api/{version}/traceroute

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
host Target host String yes
probeid Probe identifier Integer no A random probe
Response Attributes
Attribute Description Type
traceroute.result Traceroute output String
traceroute.probeid Probe identifier Integer
traceroute.probedescription Probe description String
Examples
Request

GET api/2.0/traceroute?host=pingdom.com&probeid=23

Response
{
      "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"
      }
    }

Back to top