API 2.1

Pingdom API

header-bg-small-gray

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/2.1/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
userids Comma-separated list of user identifiers. Limit results to actions sent to these users. String no All users
status Comma-separated list of statuses. Limit results to actions with these statuses. String (pending, 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).username Name of alerted user String
actions.alerts.(entry).userid Identifier of alerted user 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.1/actions?limit=2

Response
{
    "actions": {
        "alerts": [
            {
                "username" : "John Doe",
                "userid" : 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
            }, {
                "username" : "John Doe",
                "userid" : 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/2.1/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.1/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/2.1/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/2.1/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
showencryption If set, show encryption setting for each check Boolean no false
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
include_severity Include severity level for each check. 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
checks.(entry).probe_filters Filters used for probe selections Array
checks.(entry).ipv6 Use ipv6 instead of ipv4 Boolean
counts.total Total number of checks Integer
counts.filtered Number of checks after tags filter was applied Integer
counts.limited Number of checks after limit was applied Integer
Examples

Get all checks

Request

GET /api/2.1/checks&include_tags=true&tags=nginx,apache,ssh&limit=3

Response
{
    "checks": [
        {
            "hostname": "example.com",
            "id": 85975,
            "created": 1297181273,
            "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,
            "created": 1297181255,
            "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,
            "created": 1297181243,
            "lasterrortime": 1300527997,
            "lastresponsetime": 800,
            "lasttesttime": 1300977337,
            "name": "My check 3",
            "resolution": 1,
            "status": "down",
            "type": "http",
            "tags": [
                {
                    "name": "apache",
                    "type": "a",
                    "count": 2
                }
            ]
        }
    ],
    "counts": {
        "total": 55,
        "limited": 3,
        "filtered": 5
    }
}

Back to top

Method: Get Detailed Check Information
Description

Returns a detailed description of a specified check.

URL Syntax

/api/2.1/checks/{checkid}

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
include_teams Include team connections for check. Boolean no false
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.userids.(entry) Identifier of users who should receive alerts Integer
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
check.ipv6 Use ipv6 instead of ipv4 Boolean
check.responsetime_threshold Triggers a down alert if the response time exceeds threshold specified in ms Integer
check.integrationids.(entry) Identifier of integration which should receive alerts Integer
check.teams.(entry).id Identifier of team which should receive alerts Integer
check.teams.(entry).name Name of team which should receive alerts String
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 value should match header name String or List
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.1/checks/85975

Response
{
  "check" : {
    "id" : 85975,
    "name" : "My check 7",
    "resolution" : 1,
    "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/)"
          "Cookie": ["sessionid=123", "lastvisited=1293142347"]
        }
      }
    },
    "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/2.1/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
userids User identifiers. For example userids=154325,465231,765871 Comma separated Integers no
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
probe_filters Filters used for probe selections. Overwrites previous filters for check. To remove all filters from a check, use an empty value Comma separated key:value pairs 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
responsetime_threshold Triggers a down alert if the response time exceeds threshold specified in ms (Not available for Starter and Free plans.) Integer no 30000
integrationids Integration identifiers. For example integrationids=11,22,33 Comma separated Integers no
teamids Teams to alert Comma separated Integers 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.1/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.1/checks

body:

name=My+new+SMTP+check&type=smtp&resolution=15&sendnotificationwhendown=1&userids=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/2.1/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
userids User identifiers. For example userids=154325,465231,765871 Comma separated Integers 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
checkids Specify which checks to bulk modify, comma separated list. Comma separated integers 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
probe_filters Filters used for probe selections. Overwrites previous filters for check. To remove all filters from a check, use an empty value 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
responsetime_threshold Triggers a down alert if the response time exceeds threshold specified in ms (Not available for Starter and Free plans.) Integer no 30000
integrationids Integration identifiers. For example integrationids=11,22,33 Comma separated Integers no
teamids Teams to alert Comma separated Integers 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.1/checks/138632

body:

auth=newuser%3Anewpassword&resolution=30

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

Pause check 138632

Request

PUT /api/2.1/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/2.1/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.1/checks

body:

paused=true

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

Resume all checks

Request

PUT /api/2.1/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/2.1/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.1/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/2.1/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.1/checks

body:

delcheckids=134536,134539,134551

Response
{
   "message":"Deletion of checks 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/2.1/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.useddefault Total number of default check slots Integer
credits.usedtransaction Total number of transaction check slots 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
credits.autofillsms_amount The amount of sms to purchase when "autofillsms_when_left" is triggered Integer
credits.autofillsms_when_left The amount of sms left that is going to trigger purchase of sms Integer
credits.max_sms_overage The amount of overage SMSes that may be used, or null if SMS overage is not enabled. Integer
credits.availablerumsites Open RUM site slots available Integer
credits.usedrumsites Number of used RUM sites Integer
credits.maxrumfilters Number of maximum rum filters Integer
credits.maxrumpageviews Number of maximum pageviews per month Integer
Examples

Get credits list

Request

GET /api/2.1/credits

Response
{
    "credits": {
        "checklimit": 18,
        "availablechecks": 5,
        "useddefault": 6,
        "usedtransaction": 7,
        "availablesms": 20,
        "availablesmstests": 7,
        "autofillsms": false,
        "autofillsms_amount": 0,
        "autofillsms_when_left": 0,
        "max_sms_overage": 50,
        "availablerumsites": 4,
        "usedrumsites": 1,
        "maxrumfilters": 10,
        "maxrumpageviews": 100000
    }
}

Back to top

Resource: Maintenance

Method: Get maintenance windows list
Description

Returns a list of user's maintenance windows.

URL Syntax

/api/2.1/maintenance

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
limit Count of items to list. Integer no
offset Offset of the list. Integer no
orderby Order by the specific property of the maintenance window. String('description', from', 'to', 'effectiveto') no
order Order a-z for asc z-a for desc. String('asc', 'desc') no 'asc'
Response Attributes
Attribute Description Type
maintenance A list of maintenance windows Array
maintenance.(entry) Maintenance window body Object
maintenance.(entry).id Maintenance window identifier Integer
maintenance.(entry).description Description String
maintenance.(entry).from Initial maintenance window start. Format UNIX time. Integer
maintenance.(entry).to Initial maintenance window end. Format UNIX time. Integer
maintenance.(entry).recurrencetype Type of recurrence. String('none', 'day', 'week', 'month')
maintenance.(entry).repeatevery Repeat every n-th day/week/month Integer
maintenance.(entry).effectiveto Recurrence end. Format UNIX time. Integer
maintenance.(entry).checks Connected checks Object
maintenance.(entry).checks.tms List of connected Transaction checks Array
maintenance.(entry).checks.tms.(entry) Id of connected Transaction check Integer
maintenance.(entry).checks.uptime List of connected Uptime checks Array
maintenance.(entry).checks.uptime.(entry) Id of connected Uptime check Integer
Examples

Get all user's maintenance windows

Request

GET /api/2.1/maintenance

Response
{
   "maintenance": [
        {
            "id": 1,
            "description": "Maintenance window from DB",
            "from": 1497520800,
            "to": 1497574800,
            "recurrencetype": "none",
            "repeatevery": 0,
            "effectiveto": 1497574800,
            "checks": {
                "uptime": [506206, 506233, 222],
                "tms": [123, 111]
            }
        },
        {
            "id": 2,
            "description": "Another maintenance window from DB",
            "from": 1497574800,
            "to": 1497578400,
            "recurrencetype": "none",
            "repeatevery": 0,
            "effectiveto": 1497578400,
            "checks": {
                "uptime": [],
                "tms": []
            }
        }
   ]
}

Back to top

Method: Get maintenance window detail
Description

Returns the maintenance window specified by its id.

URL Syntax

/api/2.1/maintenance/{id}

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
maintenance.id Maintenance window identifier Integer
maintenance.description Description String
maintenance.from Initial maintenance window start. Format UNIX time. Integer
maintenance.to Initial maintenance window end. Format UNIX time. Integer
maintenance.recurrencetype Type of recurrence. String('none', 'day', 'week', 'month')
maintenance.repeatevery Repeat every n-th day/week/month Integer
maintenance.effectiveto Recurrence end. Format UNIX time. Integer
maintenance.checks Connected checks Object
maintenance.checks.tms List of connected TMS checks Array
maintenance.checks.tms.(entry) Id of connected TMS check Integer
maintenance.checks.uptime List of connected Uptime checks Array
maintenance.checks.uptime.(entry) Id of connected Uptime check Integer
Examples

Get maintenance window detail

Request

GET /api/2.1/maintenance/456

Response
{
    "maintenance": {
        "id": 456,
        "description": "Particular maintenance window",
        "from": 1497520800,
        "to": 1497574800,
        "recurrencetype": "none",
        "repeatevery": 0,
        "effectiveto": 1497574800,
        "checks": {
            "uptime": [506206, 506233, 222],
            "tms": [123, 111]
        }
    }
}

Back to top

Method: Create new maintenance window
Description

Create new maintenance window.

URL Syntax

/api/2.1/maintenance

HTTP Method

POST

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
description Description String yes
from Initial maintenance window start. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) Integer yes
to Initial maintenance window end. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) Integer yes
recurrencetype Type of recurrence. String('none', 'day', 'week', 'month') no 'none'
repeatevery Repeat every n-th day/week/month Integer no 0
effectiveto Recurrence end. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) Integer no Equal to `to`
uptimeids Identifiers of uptime checks to assign to the maintenance window Comma separated Integers no
tmsids Identifiers of transaction checks to assign to the maintenance window Comma separated Integers no
Response Attributes
Attribute Description Type
maintenance.id Unique id of the new maintenance window Integer
Examples

Create new maintenance window

Request

POST /api/2.1/maintenance

body:

description=Some%20description%20of%20the%20maintenance%20window&from=1500471702&to=1500475302

Response
{
    "maintenance": {
        "id": 666
    }
}

Back to top

Method: Modify the maintenance window
Description

Modify the maintenance window.

URL Syntax

/api/2.1/maintenance/{id}

HTTP Method

PUT

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
description Description String no
from Initial maintenance window start. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) Integer yes
to Initial maintenance window end. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) Integer yes
recurrencetype Type of recurrence. String('none', 'day', 'week', 'month') no 'none'
repeatevery Repeat every n-th day/week/month Integer no 0
effectiveto Recurrence end. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) Integer no Equal to `to`
uptimeids Identifiers of uptime checks to assign to the maintenance window Comma separated Integers no
tmsids Identifiers of transaction checks to assign to the maintenance window Comma separated Integers no
Response Attributes
Attribute Description Type
message Modification result description String
Examples

Modify the maintenance window

Request

PUT /api/2.1/maintenance/12345

body:

description=Modified%20maintenance%20window

Response
{
    "message": "Maintenance window successfully modified!"
}

Back to top

Method: Delete the maintenance window
Description

Delete the maintenance window. Note that only future maintenance window can be deleted.

URL Syntax

/api/2.1/maintenance/{id}

HTTP Method

DELETE

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
message Result description String
Examples

Delete the maintenance window 12345

Request

DELETE /api/2.1/maintenance/12345

Response
{
    "message": "Maintenance window successfully deleted!"
}

Back to top

Method: Delete multiple maintenance windows
Description

Delete multiple maintenance windows. Note that only future maintenance windows can be deleted.

URL Syntax

/api/2.1/maintenance

HTTP Method

DELETE

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
maintenanceids Comma-separated list of identifiers of maintenance windows to be deleted. String yes
Response Attributes
Attribute Description Type
message Result description String
Examples

Delete the maintenance windows 1, 2, 3, 4 and 5

Request

DELETE /api/2.1/maintenance

body:

maintenanceids=1,2,3,4,5

Response
{
   "message":"5 maintenance windows successfully deleted."
}

Back to top

Resource: Maintenance occurrences

Method: Get maintenance occurrence.
Description

Gets a maintenance occurrence details specified by its identifier.

URL Syntax

/api/2.1/maintenance.occurrences/{id}

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
id Identifier of an occurence. Integer
maintenanceid Identifier of the related maintenance window. Integer
from Beginning of the occurrence. Format UNIX timestamp. Integer
to The end of the occurrence. Format UNIX timestamp. Integer
Examples

Get the detail of occurrence 57

Request

GET /api/2.1/maintenance.occurrences/57

Response
{
    "occurrence": {
        "id": 57,
        "maintenanceid": 44,
        "from": 1501714800,
        "to": 1501719300
    }
}

Back to top

Method: Get maintenance occurrences list
Description

Returns a list of maintenance occurrences.

URL Syntax

/api/2.1/maintenance.occurrences

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
maintenanceid Maintenance window identifier. (List only occurrences of a specific maintenance window.) Integer no
from Effective from (unix timestamp). (List occurrences which are effective from the specified unix timestamp. If not specified, current timestamp is used.) Integer no Current timestamp
to Effective to (unix timestamp). (List occurrences which are effective to the specified unix timestamp.) Integer no
Response Attributes
Attribute Description Type
occurrences A list of maintenance occurrences. Array
occurrences.(entry) Maintenance occurrence. Object
occurrences.(entry).id Identifier of an occurence. Integer
occurrences.(entry).maintenanceid Identifier of the related maintenance window. Integer
occurrences.(entry).from Beginning of the occurrence. Format UNIX timestamp. Integer
occurrences.(entry).to The end of the occurrence. Format UNIX timestamp. Integer
Examples

Get the occurrences of the maintenance windows 44 that are effective from 2017-08-02T00:00:00 to 2017-08-02T23:59:59

Request

GET /api/2.1/maintenance.occurrences?maintenanceid=44&from=1501632000&to=1501718399

Response
{
   "occurrences": [
        {
            "id": 455,
            "maintenanceid": 44,
            "from": 1501628400,
            "to": 1501632900,
        },
        {
            "id": 456,
            "maintenanceid": 44,
            "from": 1501714800,
            "to": 1501719300,
        }
   ]
}

Back to top

Method: Modify maintenance occurrence
Description

Modifies a maintenance occurrence specified by its identifier.

URL Syntax

/api/2.1/maintenance.occurrences/{id}

HTTP Method

PUT

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
from Beginning of the maintenance occurrence. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) Integer no
to End of the maintenance occurrence. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.) Integer no
Response Attributes
Attribute Description Type
message Modification result description String
Examples

Modify the maintenance occurrence 666

Request

PUT /api/2.1/maintenance.occurrences/666

body:

from=1500471702&to=1500475302

Response
{
    "message": "Occurrence successfully modified!"
}

Back to top

Method: Delete maintenance occurrence.
Description

Deletes the maintenance occurrence specified by its identifier. Note that only future occurrences can be deleted.

URL Syntax

/api/2.1/maintenance.occurrences/{id}

HTTP Method

DELETE

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
message Result description String
Examples

Delete the maintenance window occurrence 666

Request

DELETE /api/2.1/maintenance.occurrences/666

Response
{
    "message": "Occurrence successfully deleted!"
}

Back to top

Method: Delete multiple maintenance occurrences.
Description

Deletes multiple maintenance occurrences specified by their identifiers. Note that only future occurrences can be deleted.

URL Syntax

/api/2.1/maintenance.occurrences

HTTP Method

DELETE

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
occurrenceids Comma-separated list of identifiers of maintenance occurrences to delete. String yes
Response Attributes
Attribute Description Type
message Result description String
Examples

Delete the occurrences 1, 2, 3, 4 and 5

Request

DELETE /api/2.1/maintenance.occurrences

body:

occurrenceids=1,2,3,4,5

Response
{
   "message":"5 occurrences successfully deleted."
}

Back to top

Resource: Probes

Method: Get Probe Server List
Description

Returns a list of all Pingdom probe servers for Uptime and Transaction checks.

URL Syntax

/api/2.1/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
onlytms Return only active transaction monitor 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 IPv4 address String
probes.(entry).ipv6 IPv6 address (not all probes have this) String
probes.(entry).countryiso Country ISO code String
Examples

Get all (existing) probes

Request

GET /api/2.1/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/2.1/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.1/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/2.1/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).include_paused Should include paused checks or not Boolean
Examples
Request

GET /api/2.1/reports.email

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

Back to top

Method: Create Email Report
Description

Creates a new email report.

URL Syntax

/api/2.1/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
additionalemails Comma separated list of additional receiving emails String no
include_paused Should include paused checks or not Boolean no true
Response Attributes
Attribute Description Type
message Message String
Examples
Request

POST /api/2.1/reports.email

body:

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

Response
{
   "message":"Subscription added"
}

Back to top

Method: Modify Email Report
Description

Modify an email report.

URL Syntax

/api/2.1/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
additionalemails Comma separated list of additional receiving emails String no
include_paused Should include paused checks or not Boolean no true
Response Attributes
Attribute Description Type
message Message String
Examples
Request

PUT /api/2.1/reports.email/634253

body:

name=My+subscription+modified&frequency=monthly

Response
{
   "message":"Subscription modified"
}

Back to top

Method: Delete Email Report
Description

Delete an email report.

URL Syntax

/api/2.1/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.1/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/2.1/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.1/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/2.1/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.1/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/2.1/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.1/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/2.1/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.1/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/2.1/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.1/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/2.1/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.1/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/2.1/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.1/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/2.1/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.1/servertime

Response
{
  "servertime" : 1294237910
}

Back to top

Resource: Settings

Method: Get Account Settings
Description

Returns all account-specific settings.

URL Syntax

/api/2.1/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 Account Email String
settings.billing_email Billing 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.description Account description 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.external_reference Purchase order or external reference 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.1/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" : "",
      "external_reference": "",
      "description" : "My Personal Account",
      "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/2.1/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 Account Email (Please note that your email is used for authentication purposes such as using this API or logging into the My Pingdom) String no
billing_email Billing Email (Please note that your email is used for authentication purposes such as using this API or logging into the My Pingdom) 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
description Account description 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
updaterenewal Update renewal product for accounts with renewal set to PINGDOM_*_TRIAL_ENDED, if they supply enough contact information to be invoiceable (according to swedish law). Boolean no true
Response Attributes
Attribute Description Type
Examples

Change company name to Pingdom and state to Neverland

Request

PUT /api/2.1/settings

body:

company=Pingdom&state=Neverland

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

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/2.1/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
probe_filters Filters used for probe selections. Comma separated key:value pairs no
ipv6 Use ipv6 instead of ipv4 Boolean no
responsetime_threshold Triggers a down alert if the response time exceeds threshold specified in ms (Not available for Starter and Free plans.) Integer no 30000
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.1/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: 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/2.1/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.1/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.1/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/2.1/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.1/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/2.1/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.1/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/2.1/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.1/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/2.1/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.1/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: Team

Method: Get Teams
Description

Returns a list of all teams.

URL Syntax

/api/2.1/teams

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
teams A list of teams Array
teams.(entry).id Team identifier String
teams.(entry).name Team name String
teams.(entry).users List of users in team Array
teams.(entry).users.(entry).id User identifier String
teams.(entry).users.(entry).email User email String
teams.(entry).users.(entry).name User name String
Examples

Get all teams

Request

GET /api/2.1/teams

Response
{
    "teams": [
        {
            "id": "1",
            "name": "Team Rocket",
            "users": [
                {
                    "id": "1",
                    "email": "giovanni@team-rocket.org",
                    "name": "Giovanni"
                }
            ]
        },
        {
            "id": "2",
            "name": "The A-Team",
            "users": [
                {
                    "id": "2",
                    "email": "hannibal@ateam.org",
                    "name": "John \"Hannibal\" Smith"
                },
                {
                    "id": "3",
                    "email": "faceman@ateam.org",
                    "name": "Templeton \"Face(man)\" Peck"
                }
            ]
        }
    ]
}

Back to top

Method: Get Team
Description

Returns team information.

URL Syntax

/api/2.1/teams/{teamid}

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
team Team Object
team.id Team identifier String
team.name Team name String
team.users List of users in team Array
team.users.(entry).id User identifier String
team.users.(entry).email User email String
team.users.(entry).name User name String
Examples

Get team 1

Request

GET /api/2.1/teams/1

Response
{
    "team": {
        "id": "1",
        "name": "Team Rocket",
        "users": [
            {
                "id": "1",
                "email": "giovanni@team-rocket.org",
                "name": "Giovanni"
            }
        ]
    }
}

Back to top

Method: Create Team
Description

Creates a new team.

URL Syntax

/api/2.1/teams

HTTP Method

POST

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
name Name String yes
userids Users to make team from Comma-separated integers no
Response Attributes
Attribute Description Type
id Team identifier Integer
name Team name String
users List of users in team Array
users.(entry).id User identifier String
users.(entry).email User email String
users.(entry).name User name String
Examples

Create a new team

Request

POST /api/2.1/teams

body:

name=Operations&userids=10034512,10043154

Response
{
    "id": 65,
    "name": "Operations",
    "users": [
        {
            "id": "10034512",
            "email": "hannibal@ateam.org",
            "name": "John \"Hannibal\" Smith"
        },
        {
            "id": "10043154",
            "email": "faceman@ateam.org",
            "name": "Templeton \"Face(man)\" Peck"
        }
    ]
}

Back to top

Method: Update Team
Description

Update a team.

URL Syntax

/api/2.1/teams/{teamid}

HTTP Method

PUT

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
name Name String no
userids Users to make team from Comma-separated integers no
Response Attributes
Attribute Description Type
id Team id Array
name Team name String
users List of users in team Array
users.(entry).id User identifier String
users.(entry).email User email String
users.(entry).name User name String
Examples

Create a new team

Request

PUT /api/2.1/teams/1234

body:

name=Operations&userids=10034512,10043154

Response
{
    "id": 65,
    "name": "Operations",
    "users": [
        {
            "id": "10034512",
            "email": "hannibal@ateam.org",
            "name": "John \"Hannibal\" Smith"
        },
        {
            "id": "10043154",
            "email": "faceman@ateam.org",
            "name": "Templeton \"Face(man)\" Peck"
        }
    ]
}

Back to top

Resource: Teams

Method: Delete Team
Description

Remove one or more team.

URL Syntax

/api/2.1/teams/{teamid}

HTTP Method

DELETE

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
success If removal succeeded or not Boolean
Examples

Delete teams

Request

DELETE /api/2.1/teams/1234

Response
{
    "success": true
}

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/2.1/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.1/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

Resource: Users

Method: Get list of users and contact targets
Description

Returns a list of all users and contact targets

URL Syntax

/api/2.1/users

HTTP Method

GET

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
Response Attributes
Attribute Description Type
users A list of users Array
users.(entry).id User identifier Integer
users.(entry).paused If user is paused Integer
users.(entry).name User name String
users.(entry).sms List of SMS targets Array
users.(entry).email List of EMAIL targets Array
Examples

Get all users

Request

GET /api/2.1/users

Response
{
  "users": [
    {
      "id": 1,
      "name": "User 1",
      "paused": "NO",
      "sms": [
        {
          "id": 1,
          "severity": "HIGH",
          "country_code": "46",
          "number": "71234567",
          "provider": "nexmo"
        }
      ],
      "email": [
        {
          "id": 2,
          "severity": "HIGH",
          "address": "user1@example.com"
        }
      ]
    },
    {
      "id": 2,
      "name": "User 2",
      "paused": "YES",
      "sms": [
        {
          "id": 4,
          "severity": "HIGH",
          "country_code": "46",
          "number": "709876543",
          "provider": "nexmo"
        }
      ]
    }
  ]
}

Back to top

Method: Create user
Description

Creates a new user.

URL Syntax

/api/2.1/users

HTTP Method

POST

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
name Name String yes
Response Attributes
Attribute Description Type
user User Array
Examples

Create a new user

Request

POST /api/2.1/users

body:

name=User1

Response
{
   "user": {
        "id": 3
   }
}

Back to top

Method: Modify User
Description

Modify a User.

URL Syntax

/api/2.1/users/{userid}

HTTP Method

PUT

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
name Name String yes
primary Primary contact String no
paused If user should be paused String no NO
Response Attributes
Attribute Description Type
message Message String
Examples

Change name and primary status for user 3

Request

PUT /api/2.1/users/3

body:

name=Updated%20Name&primary=YES

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

Back to top

Method: Modify Contact Target
Description

Modify a Contact Target.

URL Syntax

/api/2.1/users/{userid}/{targetid}

HTTP Method

PUT

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
email Email String no
number Cellphone number, without the country code part. (Requires countrycode and provider) String no
countrycode Cellphone country code (Requires number) String no
provider SMS provider (Requires number and countrycode) String yes NEXMO
severitylevel Severity level for target String no HIGH
Response Attributes
Attribute Description Type
message Message String
Examples

Change email on contact target 11 for user 3

Request

POST /api/2.1/users/3/11

body:

email=anotheresampleemail@example.com

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

Back to top

Method: Delete User
Description

Deletes a user.

URL Syntax

/api/2.1/users/{userid}

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 user 1

Request

DELETE /api/2.1/users/1

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

Back to top

Method: Delete contact target
Description

Deletes a contacts target.

URL Syntax

/api/2.1/users/{userid}/{targetid}

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 target 2 for user 1

Request

DELETE /api/2.1/users

Response
{
   "message":"Deletion of contact target successful"
}

Back to top

Resource: User

Method: Create a new contact target
Description

Creates a new contact target.

URL Syntax

/api/2.1/users/{userid}

HTTP Method

POST

Successful HTTP Response

200

Parameters
Parameter name Description Type Mandatory Default
email Email String no
number Cellphone number, without the country code part. (Requires countrycode) String no
countrycode Cellphone country code (Requires number) String no
provider SMS provider (Requires number and countrycode) String no NEXMO
severitylevel Severity level for target String no HIGH
Response Attributes
Attribute Description Type
contact_target Contact Target Array
Examples

Create a contact target for user 3

Request

POST /api/2.1/users/3

body:

email=example1@example.com&number=0701234567&countrycode=46&provider=nexmo&severitylevel=high

Response
{
   "contact_target": {
        "id": 11
   }
}

Back to top

Try it free for 14 days

Start monitoring your website’s availability

Start 14-day free trial

Get started now and you can cancel at any time.

Start monitoring for free