× Cookies! The Pingdom website uses cookies to make your online experience easier and better. By using our website, you consent to our use of cookies. For more information, see our Cookie Policy. Product Pricing Resources Support Tools Log in Sign up Product uptime-small Created with Sketch. Uptime monitoring Test your site’s availability from all over the world. alerting-small Alerting Effective alerting for when you need to be the first to know. pagespeed-small Page speed monitoring Examine and optimize the load performance of your website. performance-small Visitor Insights (RUM) Enhance your site performance with data from actual site visitors. transactions-small Transaction monitoring Help ensure your most vital site interactions function smoothly. server-small Server monitor The easier way to monitor servers and web applications. Product Overview Resources api-small Pingdom API Automate your Pingdom interactions with our REST API Using Pingdom Resources Tutorials & Guides Mobile apps Downloads Brand assets Webhooks Don't take our word for it! Read some of our Customer Stories Who are we? Read our story Pricing Support Tools Log in Sign up API Pingdom API header-bg-small-gray Select version: 2.1 2.0 Index Authentication Multi-User Authentication Server Address Providing Parameters HTTP/1.1 Status Code Definitions JSON Responses Limits gzip Best Practices PHP Code Example REST Requests Resource: Actions Method: Get Actions (Alerts) List Resource: Analysis Method: Get Root Cause Analysis Results List Method: Get Raw Analysis Results Resource: Checks Method: Get Check List Method: Get Detailed Check Information Method: Create New Check Method: Modify Check Method: Modify Multiple Checks Method: Delete Check Method: Delete Multiple Checks Resource: Contacts Method: Get Contacts List Resource: Credits Method: Get Credits List Resource: Maintenance Method: Get maintenance windows list Method: Get maintenance window detail Method: Create new maintenance window Method: Modify the maintenance window Method: Delete the maintenance window Method: Delete multiple maintenance windows Resource: Maintenance occurrences Method: Get maintenance occurrence Method: Get maintenance occurrences list Method: Modify maintenance occurrence Method: Delete maintenance occurrence Method: Delete multiple maintenance occurrences Resource: Probes Method: Get Probe Server List Resource: Reference Method: Get Reference Resource: Reports.email Method: Get Email Report Subscription List Method: Create Email Report Method: Modify Email Report Method: Delete Email Report Resource: Reports.public Method: Get Public Report List Method: Publish Public Report Method: Withdraw Public Report Resource: Reports.shared Method: Get Shared Reports (Banners) List Method: Create Shared Report (Banner) Method: Delete Shared Report (Banner) Resource: Results Method: Get Raw Check Results Resource: Servertime Method: Get Current Server Time Resource: Settings Method: Get Account Settings Method: Modify Account Settings Resource: Single Method: Make A Single Test Resource: Summary.average Method: Get A Response Time / Uptime Average Resource: Summary.hoursofday Method: Get Response Time Averages For Each Hour Of The Day Resource: Summary.outage Method: Get List of Outages Resource: Summary.performance Method: Get Intervals of Average Response Time and Uptime During a Given Interval Resource: Summary.probes Method: Get Active Probes For A Period Resource: Traceroute Method: Make A Traceroute 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.0/actions HTTP Method GET Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default from Only include actions generated later than this timestamp. Format is UNIX time. Integer no to Only include actions generated prior to this timestamp. Format is UNIX time. Integer no limit Limits the number of returned results to the specified quantity. Integer (max 300) no 100 offset Offset for listing. Integer no 0 checkids Comma-separated list of check identifiers. Limit results to actions generated from these checks. String no contactids Comma-separated list of contact identifiers. Limit results to actions sent to these contacts. String no All contacts status Comma-separated list of statuses. Limit results to actions with these statuses. String (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).contactname Name of alerted contact String actions.alerts.(entry).contactid Identifier of alerted contact String actions.alerts.(entry).checkid Identifier of check String actions.alerts.(entry).time Time of alert generation. Format UNIX time Integer actions.alerts.(entry).via Alert medium String (email, sms, twitter, iphone, android) actions.alerts.(entry).status Alert status String (sent, delivered, error, notdelivered, nocredits) actions.alerts.(entry).messageshort Short description of message String actions.alerts.(entry).messagefull Full message body String actions.alerts.(entry).sentto Target address, phone number etc String actions.alerts.(entry).charged True if your account was charged for this message Boolean Examples Get a list of the latest alerts. Request GET /api/2.0/actions?limit=2 Response { "actions": { "alerts": [ { "contactname" : "John Doe", "contactid" : 111250, "checkid" : 241688, "time" : 1292248276, "via" : "sms", "status" : "delivered", "messageshort" : "up", "messagefull" : "PingdomAlert UP: MyCheck (example.com) is UP again at 2010-12-13 14:50:54. Downtime: 12m.", "sentto" : "46-555555", "charged" : true }, { "contactname" : "John Doe", "contactid" : 111250, "checkid" : 241688, "time" : 1292248254, "via" : "email", "status" : "sent", "messageshort" : "up", "messagefull" : "FROM:alert@pingdom.com\r\nTO:john@example.com\r\nSubject:UP alert: MyCheck (example.com) is UP\r\n\r\nPingdomAlert UP:\r\nMyCheck (example.com) is UP again at 2010-12-13 14:50:54, after 12m of downtime.", "sentto" : "john@example.com", "charged" : false } ] } } Back to top Resource: Analysis Method: Get Root Cause Analysis Results List Description Returns a list of the latest root cause analysis results for a specified check. URL Syntax /api/2.0/analysis/{checkid} HTTP Method GET Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default limit Limits the number of returned results to the specified quantity. Integer no 100 offset Offset for listing. (Requires limit.) Integer no 0 from Return only results with timestamp of first test greater or equal to this value. Format is UNIX timestamp. Integer no 0 to Return only results with timestamp of first test less or equal to this value. Format is UNIX timestamp. Integer no Current timestamp Response Attributes Attribute Description Type analysis.(entry).id Analysis id Integer analysis.(entry).timefirsttest Time of test that initiated the confirmation test Integer analysis.(entry).timeconfirmtest Time of the confirmation test that performed the error analysis Integer Examples Get a list of the latest analyses for check 161748 Request GET /api/2.0/analysis/161748 Response { "analysis" : [ { "id" : 28739021, "timefirsttest" : 1290441826, "timeconfirmtest" : 1290441865 }, { "id" : 28737907, "timefirsttest" : 1290440924, "timeconfirmtest" : 1290440932 }, { "id" : 28589686, "timefirsttest" : 1290263024, "timeconfirmtest" : 1290263059 }, { "id" : 28063742, "timefirsttest" : 1289647724, "timeconfirmtest" : 1289647760 } ] } Back to top Method: Get Raw Analysis Results Description Returns the raw result for a specified error analysis. This data is primarily intended for internal use, but you might be interested in it as well. However, there is no real documentation for this data at the moment. In the future, we may add a new API method that provides a more user-friendly format. URL Syntax /api/2.0/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.0/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 checks.(entry).verify_certificate Verify server certificate against the available certificate authorities 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.0/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.0/checks/{checkid} HTTP Method GET Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default Response Attributes General attributes Attribute Description Type check.id Check identifier Integer check.name Check name String check.hostname Target host String check.status Current check status String (up, down, unconfirmed_down, unknown, paused) check.resolution How often should the check be tested? (minutes) Integer check.type Contains one element representing the type of check and type-specific settings Object check.contactids.(entry) Identifier of contact who should receive alerts Integer check.sendtoemail Send alerts as email Boolean check.sendtosms Send alerts as SMS Boolean check.sendtotwitter Send alerts through Twitter Boolean check.sendtoiphone Send alerts to iPhone Boolean check.sendtoandroid Send alerts to Android Boolean check.sendnotificationwhendown Send notification when down n times Integer check.notifyagainevery Notify again every n result Integer check.notifywhenbackup Notify when back up again Boolean check.lasterrortime Timestamp of last error (if any). Format is UNIX timestamp Integer check.lasttesttime Timestamp of last test (if any). Format is UNIX timestamp Integer check.lastresponsetime Response time (in milliseconds) of last test. Integer check.created Creating time. Format is UNIX timestamp Integer 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 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 check.type.http.verify_certificate Verify server certificate against the available certificate authorities Boolean HTTP Custom attributes Attribute Description Type check.type.httpcustom.url Path to target XML file on server String check.type.httpcustom.encryption Connection encryption Boolean check.type.httpcustom.port Target port Integer check.type.http.username Username for target HTTP authentication String check.type.http.password Password for target HTTP authentication String check.type.httpcustom.additionalurls.(entry) Full URL (including hostname) to target additional XML file. String TCP attributes Attribute Description Type check.type.tcp.port Target port Integer check.type.tcp.stringtosend String to send String check.type.tcp.stringtoexpect String to expect in response String Ping attributes Attribute Description Type DNS attributes Attribute Description Type check.type.dns.nameserver DNS server to use String check.type.dns.expectedip Expected IP String UDP attributes Attribute Description Type check.type.udp.port Target port Integer check.type.udp.stringtosend String to send String check.type.udp.stringtoexpect String to expect in response String SMTP attributes Attribute Description Type check.type.smtp.port Target port Integer check.type.smtp.username Username for target SMTP authentication String check.type.smtp.password Password for target SMTP authentication String check.type.smtp.encryption Connection encryption Boolean check.type.smtp.stringtoexpect String to expect in response String POP3 attributes Attribute Description Type check.type.pop3.port Target port Integer check.type.pop3.encryption Connection encryption Boolean check.type.pop3.stringtoexpect String to expect in response String IMAP attributes Attribute Description Type check.type.imap.port Target port Integer check.type.imap.encryption Connection encryption Boolean check.type.imap.stringtoexpect String to expect in response String Examples Get detailed information about check 85975 Request GET /api/2.0/checks/85975 Response { "check" : { "id" : 85975, "name" : "My check 7", "resolution" : 1, "sendtoemail" : false, "sendtosms" : false, "sendtotwitter" : false, "sendtoiphone" : false, "sendnotificationwhendown" : 0, "notifyagainevery" : 0, "notifywhenbackup" : false, "created" : 1240394682, "type" : { "http" : { "url" : "/", "port" : 80, "requestheaders" : { "User-Agent" : "Pingdom.com_bot_version_1.4_(http://www.pingdom.com/)" "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.0/checks HTTP Method POST Successful HTTP Response 200 Parameters General parameters for ALL new checks Parameter name Description Type Mandatory Default name Check name String yes host Target host String yes type Type of check String (http, httpcustom, tcp, ping, dns, udp, smtp, pop3, imap) yes paused Paused Boolean no false resolution Check resolution Integer (1, 5, 15, 30, 60) no 5 contactids Contact identifiers. For example contactids=154325,465231,765871 Comma separated Integers no sendtoemail Send alerts as email Boolean no false sendtosms Send alerts as SMS Boolean no false sendtotwitter Send alerts through Twitter Boolean no false sendtoiphone Send alerts to iPhone Boolean no false sendtoandroid Send alerts to Android Boolean no false sendnotificationwhendown Send notification when down n times Integer no 2 notifyagainevery Notify again every n result. 0 means that no extra notifications will be sent. Integer no 0 notifywhenbackup Notify when back up again Boolean no true tags Check tags Comma separated strings no 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 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 verify_certificate Verify server certificate against the available certificate authorities Boolean no true Type-specific parameters for HTTP Custom checks Parameter name Description Type Mandatory Default url Target path to XML file on server String yes encryption Connection encryption Boolean no false port Target port Integer no 80 auth Username and password for target HTTP authentication. Example: user:password String no additionalurls ;-separated list of addidional URLs with hostname included. Example: additionalurls=www.mysite.com;www.myothersite.com String no Type-specific parameters for TCP checks Parameter name Description Type Mandatory Default port Target port Integer yes stringtosend String to send String no stringtoexpect String to expect in response String no Type-specific parameters for Ping checks Parameter name Description Type Mandatory Default Type-specific parameters for DNS checks Parameter name Description Type Mandatory Default expectedip Expected ip String yes nameserver Nameserver String yes Type-specific parameters for UDP checks Parameter name Description Type Mandatory Default port Target port Integer yes stringtosend String to send String yes stringtoexpect String to expect in response String yes Type-specific parameters for SMTP checks Parameter name Description Type Mandatory Default port Target port Integer no 25 auth Username and password for target SMTP authentication. Example: user:password String no stringtoexpect String to expect in response String no encryption Connection encryption Boolean no false Type-specific parameters for POP3 checks Parameter name Description Type Mandatory Default port Target port Integer no 110 stringtoexpect String to expect in response String no encryption Connection encryption Boolean no false Type-specific parameters for IMAP checks Parameter name Description Type Mandatory Default port Target port Integer no 143 stringtoexpect String to expect in response String no encryption Connection encryption Boolean no false Response Attributes Attribute Description Type check.id New check identifier Integer check.name New check name String Examples Create a new HTTP check for www.mydomain.com with default settings Request POST /api/2.0/checks body: name=My+new+HTTP+check&type=http&host=www.mydomain.com Response { "check":{ "id":138631, "name":"My new HTTP check" } } Create a new SMTP check for smtp.mymailserver.com with SSL/TLS encryption, provided user/password, 15 minutes check resolution, with SMS and email alerts to contacts 123456 and 789012 after 1 down result Request POST /api/2.0/checks body: name=My+new+SMTP+check&type=smtp&resolution=15&sendtoemail=true&sendtosms=true&sendnotificationwhendown=1&contactids=123456,789012&host=smtp.mymailserver.com&auth=myuser%3Amypassword&encryption=true Response { "check":{ "id":138632, "name":"My new SMTP check" } } Back to top Method: Modify Check Description Modify settings for a check. The provided settings will overwrite previous values. Settings not provided will stay the same as before the update. To clear an existing value, provide an empty value. Please note that you cannot change the type of a check once it has been created. URL Syntax /api/2.0/checks/{checkid} HTTP Method PUT Successful HTTP Response 200 Parameters General parameters for ALL checks Parameter name Description Type Mandatory Default name Check name String no host Target host String no paused Paused Boolean no resolution Check resolution Integer (1, 5, 15, 30, 60) no contactids Contact identifiers. For example contactids=154325,465231,765871 Comma separated Integers no sendtoemail Send alerts as email Boolean no sendtosms Send alerts as SMS Boolean no sendtotwitter Send alerts through Twitter Boolean no sendtoiphone Send alerts to iPhone Boolean no sendtoandroid Send alerts to Android Boolean no sendnotificationwhendown Send notification when down n times Integer no notifyagainevery Notify again every n result. 0 means that no extra notifications will be sent. Integer no notifywhenbackup Notify when back up again Boolean no 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 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 verify_certificate Verify server certificate against the available certificate authorities Boolean no true Type-specific parameters for HTTP Custom checks Parameter name Description Type Mandatory Default url Target path to XML file on server String no encryption Connection encryption Boolean no port Target port Integer no auth Username and password for target HTTP authentication. Example: user:password String no additionalurls ;-separated list of addidional URLs with hostname included. Example: additionalurls=www.mysite.com;www.myothersite.com String no Type-specific parameters for TCP checks Parameter name Description Type Mandatory Default port Target port Integer no stringtosend String to send String no stringtoexpect String to expect in response String no Type-specific parameters for Ping checks Parameter name Description Type Mandatory Default Type-specific parameters for DNS checks Parameter name Description Type Mandatory Default expectedip Expected ip String no nameserver Nameserver String no Type-specific parameters for UDP checks Parameter name Description Type Mandatory Default port Target port Integer no stringtosend String to send String no stringtoexpect String to expect in response String no Type-specific parameters for SMTP checks Parameter name Description Type Mandatory Default port Target port Integer no auth Username and password for target SMTP authentication. Example: user:password String no stringtoexpect String to expect in response String no encryption Connection encryption Boolean no Type-specific parameters for POP3 checks Parameter name Description Type Mandatory Default port Target port Integer no 110 stringtoexpect String to expect in response String no encryption Connection encryption Boolean no Type-specific parameters for IMAP checks Parameter name Description Type Mandatory Default port Target port Integer no 143 stringtoexpect String to expect in response String no encryption Connection encryption Boolean no Response Attributes Attribute Description Type message Message String Examples Change user/password and resolution on SMTP check 138632 Request PUT /api/2.0/checks/138632 body: auth=newuser%3Anewpassword&resolution=30 Response { "message":"Modification of check was successful!" } Pause check 138632 Request PUT /api/2.0/checks/138632 body: paused=true Response { "message":"Modification of check was successful!" } Back to top Method: Modify Multiple Checks Description Pause or change resolution for multiple checks in one bulk call. URL Syntax /api/2.0/checks HTTP Method PUT Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default paused Paused Boolean no resolution Check resolution Integer (1, 5, 15, 30, 60) no checkids Comma-separated list of identifiers for checks to be modified. Invalid check identifiers will be ignored. String no All checks Response Attributes Attribute Description Type message Message String Examples Pause all checks Request PUT /api/2.0/checks body: paused=true Response { "message" : "Modification of 4 checks was successful!" } Resume all checks Request PUT /api/2.0/checks body: paused=false Response { "message" : "Modification of 4 checks was successful!" } Back to top Method: Delete Check Description Deletes a check. THIS METHOD IS IRREVERSIBLE! You will lose all collected data. Be careful! URL Syntax /api/2.0/checks/{checkid} HTTP Method DELETE Successful HTTP Response 200 Parameters None Parameter name Description Type Mandatory Default Response Attributes Attribute Description Type message Message String Examples Permanently delete check 134536 Request DELETE /api/2.0/checks/134536 Response { "message":"Deletion of check was successful!" } Back to top Method: Delete Multiple Checks Description Deletes a list of checks. THIS METHOD IS IRREVERSIBLE! You will lose all collected data. Be careful! URL Syntax /api/2.0/checks HTTP Method DELETE Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default delcheckids Comma-separated list of identifiers for checks to be deleted. String yes Response Attributes Attribute Description Type message Message String Examples Permanently delete checks 134536, 134539 and 134551 Request DELETE /api/2.0/checks body: delcheckids=134536,134539,134551 Response { "message":"Deletion of checks was successful!" } Back to top Resource: Contacts Method: Get Contacts List Description Returns a list of all contacts. URL Syntax /api/2.0/contacts HTTP Method GET Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default limit Limits the number of returned contacts to the specified quantity. Integer no 100 offset Offset for listing. (Requires limit.) Integer no 0 Response Attributes Attribute Description Type contacts.(entry).id Contact identifier Integer contacts.(entry).name Contact name, (u) for Pingdom User and (c) for Notification Contact String contacts.(entry).email Contact email String contacts.(entry).cellphone Contact cellphone String contacts.(entry).countryiso Cellphone country ISO code String contacts.(entry).defaultsmsprovider Default SMS provider String contacts.(entry).directtwitter Send Twitter messages as Direct Messages Boolean contacts.(entry).twitteruser Twitter username String contacts.(entry).iphonetokens.(entry) iPhone token String contacts.(entry).androidtokens.(entry) Android token String contacts.(entry).paused True if contact is paused Boolean contacts.(entry).type Pingdom User or Notification Contact String Examples Request GET /api/2.0/contacts Response { "contacts" : [ { "id" : 111250, "name" : "John Doe (c)", "email" : "john@johnsdomain.com", "cellphone" : "46-5555555", "countryiso" : "SE", "defaultsmsprovider" : "nexmo", "directtwitter" : false, "paused" : false, "type": "Notification contact" }, { "id" : 11254, "name" : "Jane Doe (u)", "email" : "jane@janesdomain.com", "type" : "User" } ] } 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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/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.0/probes Response { "probes":[ { "id":1, "country":"United Kingdom", "city":"Manchester", "name":"Manchester, UK", "active":true, "hostname":"s424.pingdom.com", "ip":"212.84.74.156", "countryiso":"GB" }, { "id":2, "country":"United States", "city":"New York", "name":"New York, NY", "active":true, "hostname":"s413.pingdom.com", "ip":"70.32.40.2" "countryiso":"US" }, { "id":3, "country":"Denmark", "city":"Copenhagen", "name":"Copenhagen, Denmark", "active":true, "hostname":"s416.pingdom.com", "ip":"82.103.128.63" "countryiso":"DK" } ] } Back to top Resource: Reference Method: Get Reference Description Get a reference of regions, timezones and date/time/number formats and their identifiers. URL Syntax /api/2.0/reference HTTP Method GET Successful HTTP Response 200 Parameters None Parameter name Description Type Mandatory Default Response Attributes Attribute Description Type regions.id Region identifier Integer regions.description Region description String regions.countryid Corresponding country identifier Integer regions.datetimeformatid Corresponding datetimeformat identifier Integer regions.numberformatid Corresponding numberformat identifier Integer regions.timezoneid Corresponding timezone identifier Integer timezones.id Time zone identifier Integer timezones.description Time zone description String datetimeformats.id Date/time format identifier Integer datetimeformats.description Date/time format description String numberformats.id Number format identifier Integer numberformats.description Number format description String countries.id Country id Integer countries.iso Country ISO code String countries.name Country name String phonecodes.countryid Country id (Can be mapped against countries.id) Integer phonecodes.name Country name String phonecodes.phonecode Area phone code String Examples Request GET /api/2.0/reference Response { "regions" : [ { "id" : 2, "description" : "United States (Alaska)" }, { "id" : 1, "description" : "United States (Hawaii)" }, { "id" : 3, "description" : "United States (Pacific Time)" }, { "id" : 4, "description" : "United States (Mountain Time)" }, { "id" : 5, "description" : "United States (Central Time)" }, { "id" : 6, "description" : "United States (Eastern Time)" }, { "id" : 7, "description" : "Sweden" }, { "id" : 8, "description" : "United Kingdom" }, { "id" : 9, "description" : "India" }, { "id" : 10, "description" : "Canada (Pacific Time)" }, { "id" : 11, "description" : "Canada (Mountain Time)" }, { "id" : 12, "description" : "Canada (Central Time)" }, { "id" : 13, "description" : "Canada (Eastern Time)" }, { "id" : 14, "description" : "Canada (Atlantic Time)" }, { "id" : 15, "description" : "Canada (Newfoundland)" }, { "id" : 16, "description" : "China" }, { "id" : 17, "description" : "Australia (Adelaide)" }, { "id" : 18, "description" : "Australia (Canberra, Melbourne, Sydney)" }, { "id" : 19, "description" : "Turkey" }, { "id" : 20, "description" : "Spain" }, { "id" : 21, "description" : "Brazil (Eastern Time)" }, { "id" : 22, "description" : "Brazil (Atlantic Time)" }, { "id" : 23, "description" : "Brazil (Brazil, Buenos Aires, Georgetown)" }, { "id" : 24, "description" : "Brazil (Mid-Atlantic)" }, { "id" : 25, "description" : "Indonesia (Bangkok, Hanoi, Jakarta)" }, { "id" : 26, "description" : "Indonesia (Beijing, Perth, Singapore, Hong Kong)" }, { "id" : 27, "description" : "Indonesia (Tokyo, Seoul, Osaka)" }, { "id" : 28, "description" : "Romania" }, { "id" : 29, "description" : "Mexico (Pacific Time)" }, { "id" : 30, "description" : "Mexico (Mountain Time)" }, { "id" : 31, "description" : "Mexico (Central Time)" }, { "id" : 32, "description" : "Bulgaria" }, { "id" : 33, "description" : "Portugal (Azores)" }, { "id" : 34, "description" : "Portugal (Western Europe Time, London, Lisbon)" }, { "id" : 35, "description" : "Egypt" }, { "id" : 36, "description" : "Italy" }, { "id" : 37, "description" : "Pakistan" }, { "id" : 38, "description" : "France" }, { "id" : 39, "description" : "New Zealand" }, { "id" : 40, "description" : "Australia (Lord Howe Island)" }, { "id" : 41, "description" : "New Zealand (Chatham Islands)" }, { "id" : 42, "description" : "Germany" }, { "id" : 43, "description" : "Saudi Arabia" }, { "id" : 44, "description" : "Australia (Perth)" } ], "timezones" : [ { "id" : 1, "description" : "(GMT -12:00) Eniwetok, Kwajalein" }, { "id" : 2, "description" : "(GMT -11:00) Midway Island, Samoa" }, { "id" : 3, "description" : "(GMT -10:00) Hawaii" }, { "id" : 4, "description" : "(GMT -9:00) Alaska" }, { "id" : 5, "description" : "(GMT -8:00) Pacific Time (US &amp; Canada)" }, { "id" : 6, "description" : "(GMT -7:00) Mountain Time (US &amp; Canada)" }, { "id" : 7, "description" : "(GMT -6:00) Central Time (US &amp; Can.), Mexico" }, { "id" : 8, "description" : "(GMT -5:00) Eastern Time (US &amp; Can.)" }, { "id" : 9, "description" : "(GMT -4:00) Atlantic Time (Can.)" }, { "id" : 10, "description" : "(GMT -3:30) Newfoundland" }, { "id" : 11, "description" : "(GMT -3:00) Brazil, Buenos Aires, Georgetown" }, { "id" : 12, "description" : "(GMT -2:00) Mid-Atlantic" }, { "id" : 13, "description" : "(GMT -1:00 hour) Azores" }, { "id" : 14, "description" : "(GMT) Western Europe Time, London, Lisbon" }, { "id" : 15, "description" : "(GMT +1:00 hour) Brussels, Copenhagen, Madrid" }, { "id" : 16, "description" : "(GMT +2:00) Athens, Cairo" }, { "id" : 17, "description" : "(GMT +3:00) Baghdad, Moscow, Riyadh" }, { "id" : 18, "description" : "(GMT +3:30) Tehran" }, { "id" : 19, "description" : "(GMT +4:00) Abu Dhabi, Muscat" }, { "id" : 20, "description" : "(GMT +4:30) Kabul" }, { "id" : 21, "description" : "(GMT +5:00) Islamabad, Karachi" }, { "id" : 22, "description" : "(GMT +5:30) Bombay, Calcutta, Colombo, New Delhi" }, { "id" : 23, "description" : "(GMT +6:00) Almaty, Dhaka" }, { "id" : 24, "description" : "(GMT +7:00) Bangkok, Hanoi, Jakarta" }, { "id" : 25, "description" : "(GMT +8:00) Beijing, Perth, Singapore, Hong Kong" }, { "id" : 26, "description" : "(GMT +9:00) Tokyo, Seoul, Osaka" }, { "id" : 27, "description" : "(GMT +9:30) Adelaide" }, { "id" : 28, "description" : "(GMT +10:00) Canbera, Melbourne, Sydney" }, { "id" : 29, "description" : "(GMT +11:00) Solomon Isl., New Caledonia" }, { "id" : 30, "description" : "(GMT +12:00) Auckland, Fiji, Kamchatka" }, { "id" : 32, "description" : "(GMT +10:30) Lord Howe Island" }, { "id" : 33, "description" : "(GMT +12:45) Chatham Islands" }, { "id" : 34, "description" : "(GMT +10:00) Brisbane" }, { "id" : 35, "description" : "(GMT +13:00) New Zealand Daylight Time, Tonga" }, { "id" : 36, "description" : "(GMT) Reykjavik" }, { "id" : 37, "description" : "(GMT +2:00) South African Standard Time" }, { "id" : 38, "description" : "(GMT -4:30) Caracas" }, { "id" : 39, "description" : "(GMT -6:00) Central America, El Salvador" } ], "datetimeformats" : [ { "id" : 1, "description" : "07/31/2006 02:45:05pm" }, { "id" : 2, "description" : "31/07/2006 02:45:05pm" }, { "id" : 3, "description" : "31/07/2006 14:45:05" }, { "id" : 4, "description" : "2006-07-31 14:45:05" }, { "id" : 5, "description" : "31.07.2006. 14:45:05" }, { "id" : 6, "description" : "31/07/2006 14h45m05" }, { "id" : 7, "description" : "31-07-2006 02:45:05pm" }, { "id" : 8, "description" : "31-07-2006 14:45:05" } ], "numberformats" : [ { "id" : 1, "description" : "123,456,789.00" }, { "id" : 2, "description" : "123 456 789.00" }, { "id" : 3, "description" : "123456789.00" }, { "id" : 4, "description" : "123.456.789,00" }, { "id" : 5, "description" : "123 456 789,00" }, { "id" : 6, "description" : "123456789,00" } ] } Back to top Resource: Reports.email Method: Get Email Report Subscription List Description Returns a list of email report subscriptions. URL Syntax /api/2.0/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.0/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.0/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.0/reports.email body: name=My+subscription&frequency=weekly Response { "message":"Subscription added" } Back to top Method: Modify Email Report Description Modify an email report. URL Syntax /api/2.0/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.0/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.0/reports.email/{reportid} HTTP Method DELETE Successful HTTP Response 200 Parameters None Parameter name Description Type Mandatory Default Response Attributes Attribute Description Type message Message String Examples Request DELETE /api/2.0/reports.email/634253 Response { "message":"Subscription deleted" } Back to top Resource: Reports.public Method: Get Public Report List Description Returns a list of public (web-based) reports. URL Syntax /api/2.0/reports.public HTTP Method GET Successful HTTP Response 200 Parameters None Parameter name Description Type Mandatory Default Response Attributes Attribute Description Type public.(entry).checkid Check identifier Integer public.(entry).checkname Check name String public.(entry).reporturl URL to report String Examples Request GET /api/2.0/reports.public Response { "public" : [ { "checkid" : 85975, "checkname" : "ubuntu packages", "reporturl" : "http://www.pingdom.com/reports/rwknj2rkd39h/check_overview/?name=ubuntu+packages" } ] } Back to top Method: Publish Public Report Description Activate public report for a specified check. URL Syntax /api/2.0/reports.public/{checkid} HTTP Method PUT Successful HTTP Response 200 Parameters None Parameter name Description Type Mandatory Default Response Attributes Attribute Description Type message Message String Examples Request PUT /api/2.0/reports.public/123456 Response { "message":"Check published" } Back to top Method: Withdraw Public Report Description Deactivate public report for a specified check. URL Syntax /api/2.0/reports.public/{checkid} HTTP Method DELETE Successful HTTP Response 200 Parameters None Parameter name Description Type Mandatory Default Response Attributes Attribute Description Type message Message String Examples Request DELETE /api/2.0/reports.public/123456 Response { "message":"Check unpublished" } Back to top Resource: Reports.shared Method: Get Shared Reports (Banners) List Description Returns a list of shared reports (banners). URL Syntax /api/2.0/reports.shared HTTP Method GET Successful HTTP Response 200 Parameters None Parameter name Description Type Mandatory Default Response Attributes Attribute Description Type shared.banners.(entry).id Banner identifier Integer shared.banners.(entry).name Banner name String shared.banners.(entry).checkid Check identifier Integer shared.banners.(entry).auto Automatic period activated? Boolean shared.banners.(entry).type Banner type String (response, uptime) shared.banners.(entry).url Banner URL String shared.banners.(entry).fromyear Period start: year Integer shared.banners.(entry).frommonth Period start: month Integer shared.banners.(entry).fromday Period start: day Integer shared.banners.(entry).toyear Period end: year Integer shared.banners.(entry).tomonth Period end: month Integer shared.banners.(entry).today Period end: day Integer Examples Request GET /api/2.0/reports.shared Response { "shared" : { "banners" : [ { "id" : "9338512f", "name" : "mydomain.com", "checkid" : 241688, "auto" : true, "type" : "uptime", "url" : "http://share.pingdom.com/banners/9338512f" }, { "id" : "476a37ba", "name" : "myotherdomain.com", "checkid" : 241688, "auto" : true, "type" : "uptime", "url" : "http://share.pingdom.com/banners/476a37ba" } ] } } Back to top Method: Create Shared Report (Banner) Description Create a shared report (banner). URL Syntax /api/2.0/reports.shared HTTP Method POST Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default sharedtype Shared report type. For now, only "banner" is valid String (banner) yes checkid Identifier of target check Integer yes auto Automatic period (If false, requires: fromyear, frommonth, fromday, toyear, tomonth, today) Boolean no true fromyear Period start: year Integer no frommonth Period start: month Integer no fromday Period start: day Integer no toyear Period end: year Integer no tomonth Period end: month Integer no today Period end: day Integer no type Banner type String (uptime, response) no uptime Response Attributes Attribute Description Type message Message String Examples Request POST /api/2.0/reports.shared body: sharedtype=banner&checkid=123456 Response { "message":"Banner created" } Back to top Method: Delete Shared Report (Banner) Description Delete a shared report (banner). URL Syntax /api/2.0/reports.shared/{reportid} HTTP Method DELETE Successful HTTP Response 200 Parameters None Parameter name Description Type Mandatory Default Response Attributes Attribute Description Type message Message String Examples Request DELETE /api/2.0/reports.shared/476a37ba Response { "message":"Banner deleted" } Back to top Resource: Results Method: Get Raw Check Results Description Return a list of raw test results for a specified check URL Syntax /api/2.0/results/{checkid} HTTP Method GET Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default to End of period. Format is UNIX timestamp Integer no current time from Start of period. Format is UNIX timestamp Integer no 1 day prior to 'to' probes Filter to only show results from a list of probes. Format is a comma separated list of probe identifiers String no all probes status Filter to only show results with specified statuses. Format is a comma separated list of (down, up, unconfirmed, unknown) String no all statuses limit Number of results to show (Will be set to 1000 if the provided value is greater than 1000) Integer no 1000 offset Number of results to skip (Max value is 43200) Integer no 0 includeanalysis Attach available root cause analysis identifiers to corresponding results Boolean no false maxresponse Maximum response time (ms). If set, specified interval must not be larger than 31 days. Integer no minresponse Minimum response time (ms). If set, specified interval must not be larger than 31 days. Integer no Response Attributes Attribute Description Type results.(entry).probeid Probe identifier Integer results.(entry).time Time when test was performed. Format is UNIX timestamp Integer results.(entry).status Result status String (up, down, unconfirmed_down, unknown) results.(entry).responsetime Response time (in milliseconds) (Will be 0 if no response was received) Integer results.(entry).statusdesc Short status description String results.(entry).statusdesclong Long status description String results.(entry).analysisid Analysis identifier Integer activeprobes For your convinience, a list of used probes that produced the showed results Array activeprobes.(entry) Probe identifier Integer Examples Get the 5 latest results for check 85975 Request GET /api/2.0/results/85975?limit=5 Response { "results" : [ { "probeid" : 33, "time" : 1294235764, "status" : "up", "responsetime" : 91, "statusdesc" : "OK", "statusdesclong" : "OK" }, { "probeid" : 34, "time" : 1294235703, "status" : "up", "responsetime" : 442, "statusdesc" : "OK", "statusdesclong" : "OK" }, { "probeid" : 35, "time" : 1294235643, "status" : "up", "responsetime" : 187, "statusdesc" : "OK", "statusdesclong" : "OK" }, { "probeid" : 36, "time" : 1294235583, "status" : "up", "responsetime" : 403, "statusdesc" : "OK", "statusdesclong" : "OK" }, { "probeid" : 37, "time" : 1294235523, "status" : "up", "responsetime" : 111, "statusdesc" : "OK", "statusdesclong" : "OK" } ], "activeprobes" : [ 33, 34, 35, 36, 37 ] } Back to top Resource: Servertime Method: Get Current Server Time Description Get the current time of the API server. URL Syntax /api/2.0/servertime HTTP Method GET Successful HTTP Response 200 Parameters None Parameter name Description Type Mandatory Default Response Attributes Attribute Description Type servertime Current server time. Format is UNIX timestamp Integer Examples Request GET /api/2.0/servertime Response { "servertime" : 1294237910 } Back to top Resource: Settings Method: Get Account Settings Description Returns all account-specific settings. URL Syntax /api/2.0/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.0/settings Response { "settings" : { "firstname" : "John", "lastname" : "Smith", "company" : "Pingdom", "email" : "johndoe@pingdom.com", "phone" : "", "cellphone" : "46-555555555", "address" : "Pingdom Street 1", "address2" : "", "zip" : "55555", "location" : "Pingdom City", "state" : "", "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.0/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.0/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.0/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 verify_certificate Verify server certificate against the available certificate authorities Boolean no true Type-specific parameters for HTTP Custom tests Parameter name Description Type Mandatory Default url Target path to XML file on server String yes encryption Connection encryption Boolean no false port Target port Integer no 80 auth Username and password for target HTTP authentication. Example: user:password String no additionalurls ;-separated list of addidional URLs with hostname included. Example: additionalurls=www.mysite.com;www.myothersite.com String no Type-specific parameters for TCP tests Parameter name Description Type Mandatory Default port Target port Integer yes stringtosend String to send String no stringtoexpect String to expect in response String no Type-specific parameters for Ping tests Parameter name Description Type Mandatory Default Type-specific parameters for DNS tests Parameter name Description Type Mandatory Default expectedip Expected ip String yes nameserver Nameserver String yes Type-specific parameters for UDP tests Parameter name Description Type Mandatory Default port Target port Integer yes stringtosend String to send String yes stringtoexpect String to expect in response String yes Type-specific parameters for SMTP tests Parameter name Description Type Mandatory Default port Target port Integer no 25 auth Username and password for target SMTP authentication. Example: user:password String no stringtoexpect String to expect in response String no encryption Connection encryption Boolean no false Type-specific parameters for POP3 tests Parameter name Description Type Mandatory Default port Target port Integer no 110 stringtoexpect String to expect in response String no encryption Connection encryption Boolean no false Type-specific parameters for IMAP tests Parameter name Description Type Mandatory Default port Target port Integer no 143 stringtoexpect String to expect in response String no encryption Connection encryption Boolean no false Response Attributes Attribute Description Type result.status Test result status String (up, down) result.responsetime Response time in milliseconds Integer result.statusdesc Short status description String result.statusdesclong Long status description String result.probeid Probe identifier Integer result.probedesc Probe description String Examples Request GET /api/2.0/single?host=pingdom.com&type=http&probeid=17 Response { "result" : { "status" : "up", "responsetime" : 73, "statusdesc" : "OK", "statusdesclong" : "OK", "probeid" : 17, "probedesc" : "Stockholm, Sweden" } } Back to top Resource: 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.0/summary.average/{checkid} HTTP Method GET Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default from Start time of period. Format is UNIX timestamp Integer no 0 to End time of period. Format is UNIX timestamp Integer no current time probes Filter to only use results from a list of probes. Format is a comma separated list of probe identifiers String no all probes includeuptime Include uptime information Boolean no false bycountry Split response times into country groups Boolean no false byprobe Split response times into probe groups Boolean no false Response Attributes Attribute Description Type summary.responsetime.from Start time of period Integer summary.responsetime.to End time of period Integer summary.responsetime.avgresponse Total average response time in milliseconds Integer summary.responsetime.(entry).countryiso Country group ISO code Integer summary.responsetime.(entry).probeid Probe group probe identifier Integer summary.responsetime.(entry).avgresponse Group average response time in milliseconds Integer summary.status.totalup Total uptime in seconds (Please note that the accuracy of this value is depending on your check resolution) Integer summary.status.totaldown Total downtime in seconds (Please note that the accuracy of this value is depending on your check resolution) Integer summary.status.totalunknown Total unknown/unmonitored/paused in seconds (Please note that the accuracy of this value is depending on your check resolution. Also note that time before the check was created counts as unknown) Integer Examples Request GET /api/2.0/summary.average/85975 body: includeuptime=true Response { "summary" : { "responsetime" : { "from" : 0, "to" : 1294245352, "avgresponse" : 458 }, "status" : { "totalup" : 53072286, "totaldown" : 771879, "totalunknown" : 1240401138 } } } Request GET /api/2.0/summary.average/85975 body: bycountry=true Response { "summary" : { "responsetime" : { "from" : 0, "to" : 1294245226, "avgresponse" : [ { "countryiso" : "SE", "avgresponse" : 250 }, { "countryiso" : "US", "avgresponse" : 650 }, { "countryiso" : "GB", "avgresponse" : 129 }, { "countryiso" : "CA", "avgresponse" : 442 }, { "countryiso" : "NL", "avgresponse" : 162 }, { "countryiso" : "DE", "avgresponse" : 200 }, { "countryiso" : "DK", "avgresponse" : 229 }, { "countryiso" : "FR", "avgresponse" : 204 }, { "countryiso" : "ES", "avgresponse" : 285 } ] } } } Back to top Resource: Summary.hoursofday Method: Get Response Time Averages For Each Hour Of The Day Description Returns the average response time for each hour of the day (0-23) for a specific check over a selected time period. I.e. it shows you what an average day looks like during that time period. URL Syntax /api/2.0/summary.hoursofday/{checkid} HTTP Method GET Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default from Start time of period. Format is UNIX timestamp Integer no One week earlier than "to" to End time of period. Format is UNIX timestamp Integer no Current time probes Filter to only use results from a list of probes. Format is a comma separated list of probe identifiers String no all probes uselocaltime If true, use the user's local time zone for results (from and to parameters should still be specified in UTC). If false, use UTC for results. Boolean no false Response Attributes Attribute Description Type hoursofday.(entry).hour Hour of day (0-23). Please note that if data is missing for an individual hour, it's entry will not be included in the result. Integer hoursofday.(entry).avgresponse Average response time (in milliseconds) for this hour of the day Integer Examples Get averages for the last week Request GET /api/2.0/summary.hoursofday/85975 Response { "hoursofday" : [ { "hour" : 0, "avgresponse" : 259 }, { "hour" : 1, "avgresponse" : 299 }, { "hour" : 2, "avgresponse" : 259 }, { "hour" : 3, "avgresponse" : 327 }, { "hour" : 4, "avgresponse" : 302 }, "hour" : 5, "avgresponse" : 376 }, "hour" : 6, "avgresponse" : 256 }, "hour" : 7, "avgresponse" : 262 }, "hour" : 8, "avgresponse" : 328 }, "hour" : 9, "avgresponse" : 335 }, "hour" : 10, "avgresponse" : 276 }, { "hour" : 11, "avgresponse" : 291 }, { "hour" : 12, "avgresponse" : 287 }, { "hour" : 13, "avgresponse" : 267 }, { "hour" : 14, "avgresponse" : 276 }, { "hour" : 15, "avgresponse" : 266 }, { "hour" : 16, "avgresponse" : 326 }, { "hour" : 17, "avgresponse" : 292 }, { "hour" : 18, "avgresponse" : 301 }, { "hour" : 19, "avgresponse" : 270 }, { "hour" : 20, "avgresponse" : 282 }, { "hour" : 21, "avgresponse" : 262 }, { "hour" : 22, "avgresponse" : 270 }, { "hour" : 23, "avgresponse" : 253 } ] } Back to top Resource: Summary.outage Method: Get List of Outages Description Get a list of status changes for a specified check and time period. If order is speficied to descending, the list is ordered by newest first. (Default is ordered by oldest first.) URL Syntax /api/2.0/summary.outage/{checkid} HTTP Method GET Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default from Start time of period. Format is UNIX timestamp Integer no One week earlier than to to End time of period. Format is UNIX timestamp Integer no current time order Sorting order of outages. Ascending or descending. String (asc,desc) no asc Response Attributes Attribute Description Type summary.states.(entry).status Interval status String (up, down, unknown) summary.states.(entry).timefrom Interval start. Format UNIX timestamp Integer summary.states.(entry).timeto Interval end. Format UNIX timestamp Integer Examples Request GET /api/2.0/summary.outage/85975 Response { "summary" : { "states" : [ { "status" : "up", "timefrom" : 1293143523, "timeto" : 1294180263 }, { "status" : "down", "timefrom" : 1294180263, "timeto" : 1294180323 }, { "status" : "up", "timefrom" : 1294180323, "timeto" : 1294223466 }, { "status" : "down", "timefrom" : 1294223466, "timeto" : 1294223523 }, { "status" : "up", "timefrom" : 1294223523, "timeto" : 1294228503 }, { "status" : "down", "timefrom" : 1294228503, "timeto" : 1294228563 }, { "status" : "up", "timefrom" : 1294228563, "timeto" : 1294228623 }, { "status" : "down", "timefrom" : 1294228623, "timeto" : 1294228743 }, { "status" : "up", "timefrom" : 1294228743, "timeto" : 1294228803 }, { "status" : "down", "timefrom" : 1294228803, "timeto" : 1294228987 }, { "status" : "up", "timefrom" : 1294228987, "timeto" : 1294229047 }, { "status" : "down", "timefrom" : 1294229047, "timeto" : 1294229583 }, { "status" : "up", "timefrom" : 1294229583, "timeto" : 1294229643 }, { "status" : "down", "timefrom" : 1294229643, "timeto" : 1294230063 }, { "status" : "up", "timefrom" : 1294230063, "timeto" : 1294389243 } ] } } Back to top Resource: Summary.performance Method: Get Intervals of Average Response Time and Uptime During a Given Interval Description For a given interval in time, return a list of sub intervals with the given resolution. Useful for generating graphs. A sub interval may be a week, a day or an hour depending on the choosen resolution. URL Syntax /api/2.0/summary.performance/{checkid} HTTP Method GET Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default from Start time of period. Format is UNIX timestamp Integer no 10 intervals earlier than to to End time of period. Format is UNIX timestamp Integer no current time resolution Interval size String (hour, day, week) no hour includeuptime Include uptime information. Boolean no false probes Filter to only use results from a list of probes. Format is a comma separated list of probe identifiers. Can not be used if includeuptime is set to true. Also note that this can cause intervals to be omitted, since there may be no results from the desired probes in them. String no all probes order Sorting order of sub intervals. Ascending or descending. String (asc,desc) no asc Response Attributes Attribute Description Type summary.hours.(entry).starttime Hour interval start. Format UNIX timestamp Integer summary.hours.(entry).avgresponse Average response time for this interval in milliseconds Integer summary.hours.(entry).uptime Total uptime for this interval in seconds Integer summary.hours.(entry).downtime Total downtime for this interval in seconds Integer summary.hours.(entry).unmonitored Total unmonitored time for this interval in seconds Integer summary.days.(entry).starttime Day interval start. Format UNIX timestamp Integer summary.days.(entry).avgresponse Average response time for this interval in milliseconds Integer summary.days.(entry).uptime Total uptime for this interval in seconds Integer summary.days.(entry).downtime Total downtime for this interval in seconds Integer summary.days.(entry).unmonitored Total unmonitored time for this interval in seconds Integer summary.weeks.(entry).starttime Week interval start. Format UNIX timestamp Integer summary.weeks.(entry).avgresponse Average response time for this interval in milliseconds Integer summary.weeks.(entry).uptime Total uptime for this interval in seconds Integer summary.weeks.(entry).downtime Total downtime for this interval in seconds Integer summary.weeks.(entry).unmonitored Total unmonitored time for this interval in seconds Integer Examples Request GET /api/2.0/summary.performance/85975?includeuptime=true&resolution=week Response { "summary" : { "weeks" : [ { "starttime" : 1287957600, "avgresponse" : 468, "uptime" : 608400, "downtime" : 0, "unmonitored" : 0 }, { "starttime" : 1288566000, "avgresponse" : 467, "uptime" : 604620, "downtime" : 180, "unmonitored" : 0 }, { "starttime" : 1289170800, "avgresponse" : 440, "uptime" : 604680, "downtime" : 120, "unmonitored" : 0 }, { "starttime" : 1289775600, "avgresponse" : 451, "uptime" : 604680, "downtime" : 120, "unmonitored" : 0 }, { "starttime" : 1290380400, "avgresponse" : 456, "uptime" : 604680, "downtime" : 120, "unmonitored" : 0 }, { "starttime" : 1290985200, "avgresponse" : 465, "uptime" : 604496, "downtime" : 304, "unmonitored" : 0 }, { "starttime" : 1291590000, "avgresponse" : 489, "uptime" : 604610, "downtime" : 190, "unmonitored" : 0 }, { "starttime" : 1292194800, "avgresponse" : 466, "uptime" : 604800, "downtime" : 0, "unmonitored" : 0 }, { "starttime" : 1292799600, "avgresponse" : 452, "uptime" : 604680, "downtime" : 120, "unmonitored" : 0 }, { "starttime" : 1293404400, "avgresponse" : 447, "uptime" : 604800, "downtime" : 0, "unmonitored" : 0 }, { "starttime" : 1294009200, "avgresponse" : 465, "uptime" : 382511, "downtime" : 1437, "unmonitored" : 0 } ] } } Back to top Resource: Summary.probes Method: Get Active Probes For A Period Description Get a list of probes that performed tests for a specified check during a specified period. URL Syntax /api/2.0/summary.probes/{checkid} HTTP Method GET Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default from Start time of period. Format is UNIX timestamp Integer yes to End time of period. Format is UNIX timestamp Integer no current time Response Attributes Attribute Description Type probes.(entry) Probe identifier Integer Examples Request GET /api/2.0/summary.probes/85975?from=1294393564&to=1294394816 Response { "probes" : [ 43, 42, 41, 40, 39, 37, 36, 35, 34, 33, 32, 31, 30, 29, 28, 27, 24, 23, 22, 21 ] } Back to top Resource: Traceroute Method: Make A Traceroute Description Perform a traceroute to a specified target from a specified Pingdom probe. URL Syntax /api/2.0/traceroute HTTP Method GET Successful HTTP Response 200 Parameters Parameter name Description Type Mandatory Default host Target host String yes probeid Probe identifier Integer no A random probe Response Attributes Attribute Description Type traceroute.result Traceroute output String traceroute.probeid Probe identifier Integer traceroute.probedescription Probe description String Examples Request GET api/2.0/traceroute?host=pingdom.com&probeid=23 Response { "traceroute" : { "result" : "traceroute to pingdom.com (83.140.19.136), 30 hops max, 40 byte packets\n 1 67.192.120.130 (67.192.120.130) 4.803 ms 5.000 ms 5.202 ms\n 2 67.192.56.2 (67.192.56.2) 0.332 ms 0.352 ms 0.431 ms\n 3 vlan905.edge4.dfw1.rackspace.com (67.192.56.228) 0.384 ms 0.444 ms 0.497 ms\n 4 12.87.41.177 (12.87.41.177) 1.926 ms 1.983 ms *\n 5 cr1.dlstx.ip.att.net (12.122.139.122) 3.696 ms 3.725 ms 3.741 ms\n 6 dlstx01jt.ip.att.net (12.122.80.41) 1.792 ms 1.817 ms 1.840 ms\n 7 192.205.34.82 (192.205.34.82) 1.668 ms 1.828 ms 192.205.34.142 (192.205.34.142) 1.722 ms\n 8 RIX-TELECOM-AB.TenGigabitEthernet9-3.ar2.ANR3.gblx.net (64.208.169.138) 147.221 ms 146.710 ms 146.473 ms\n 9 po41-20g-r86.cr1-r85.hy-sto.se.p80.net (82.96.1.162) 146.334 ms 146.347 ms 146.776 ms\n10 83.140.54.18.cust.port80.se (83.140.54.18) 146.741 ms 146.311 ms 146.283 ms\n11 83.140.19.136 (83.140.19.136) 146.789 ms 146.710 ms 146.795 ms\n", "probeid" : 23, "probedescription" : "Dallas 4, TX" } } Back to top 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. Product Uptime Performance Transaction monitoring Alerting Page Speed Pingdom Tools Pricing Company Why Pingdom Contact Brand Assets SolarWinds Jobs Customers GDPR Resource Center Email Settings Using Pingdom API Tutorials Webhooks Downloads Mobile Apps Pingdom Help Solarwinds SolarWinds Cloud AppOptics Papertrail Loggly Latest from our blog Will HTTP/2 Make Your Site Faster? How 3rd Party Trackers Impact the Performance of the World’s Top News Sites Increased Data Retention for Visitor Insights Introducing Shareable Reports Visit Royal Pingdom Copyright © 2018 Pingdom AB. All rights reserved. Software Service Agreement, Trademarks, Terms of Use, Privacy Policy or Cookie Policy. Need help? To get in touch with our Support Team give us a call at +1 (802) 242-4077 (8am - 8pm UTC) or check out our FAQ & Knowledge Base.