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 API Token is required. You generate your Pingdom API Token inside My Pingdom. The Pingdom API Token has a property called “Access level” to define its permissions. All operations that create or modify something (e.g. checks) need the Read/Write permission. If you only need to read data using the API token, we recommend to set the access level to “Read access”.
The authentication method for using tokens is HTTP Bearer Authentication (encrypted over HTTPS). This means that you will provide your token every time you make a request. No sessions are used.
Request
GET /checks HTTP/1.1
Host: api.pingdom.com
Authorization: Bearer ofOhK18Ca6w4S_XmInGv0QPkqly-rbRBBoHsp_2FEH5QnIbH0VZhRPO3tlvrjMIKQ36VapX
Response
HTTP/1.1 200 OK
Content-Length: 13
Content-Type: application/json
{"checks":[]}
Basic Auth
For compatibility reasons, the Pingdom API allows to use HTTP Basic Authentication with tokens. In cases where this is necessary, input the API token as the username and leave the password field empty.
An example request of how that would look like with the following API token: ofOhK18Ca6w4S_XmInGv0QPkqly-rbRBBoHsp_2FEH5QnIbH0VZhRPO3tlvrjMIKQ36VapX
GET /checks HTTP/1.1
Host: api.pingdom.com
Authorization: Basic b2ZPaEsxOENhNnc0U19YbUluR3YwUVBrcWx5LXJiUkJCb0hzcF8yRkVINVFuSWJIMFZaaFJQTzN0bHZyak1JS1EzNlZhcFg6
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 JSON. This should be part of the request body. Remember to add the proper content type header to the request: Content-Type: application/json.
We still support providing parameters as a query string for POST, PUT and DELETE requests, but we recommend using JSON going forward. If you are using query strings, they 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 limits are exceeded, an HTTP 429 error code with the message "Request limit exceeded, try again later" is sent back.
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:
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);
TMS Steps Vocabulary
There are two types of transaction checks:
script: the legacy TMS check created with predefined commands in the Pingdom UI or via the public API recording: the TMS check created by recording performed actions in WPM recorder. More information about how to use it can be found in the
WPM recorder documentation
Script transaction checks
Commands
Actions to be performed for the script TMS check
| Step Name | "fn" | Required "args" | Remarks |
|---|---|---|---|
| Go to URL | go_to | url | There has to be exactly one go_to step |
| Click | click | element | label, name or CSS selector |
| Fill in field | fill | input, value | input: label, name or CSS selector, value: text |
| Check checkbox | check | checkbox | label, name or CSS selector |
| Uncheck checkbox | uncheck | checkbox | label, name or CSS selector |
| Sleep for | sleep | seconds | number (e.g. 0.1) |
| Select radio button | select_radio | radio | name of the radio button |
| Select dropdown | select | select, option | select: label, name or CSS selector, option: content, value or CSS selector |
| Basic auth login with | basic_auth | username, password | username and password as text |
| Submit form | submit | form | name or CSS selector |
| Wait for element | wait_for_element | element | label, name or CSS selector |
| Wait for element to contain | wait_for_contains | element, value | element: label, name or CSS selector, value: text |
Validations
Verify the state of the page
| Step Name | "fn" | Required "args" | Remarks |
|---|---|---|---|
| URL should be | url | url | url to be verified |
| Element should exist | exists | element | label, name or CSS selector |
| Element shouldn't exist | not_exists | element | label, name or CSS selector |
| Element should contain | contains | element, value | element: label, name or CSS selector, value: text |
| Element shouldn't containt | not_contains | element, value | element: label, name or CSS selector, value: text |
| Text field should contain | field_contains | input, value | input: label, name or CSS selector, value: text |
| Text field shouldn't contain | field_not_contains | input, value | input: label, name or CSS selector, value: text |
| Checkbox should be checked | is_checked | checkbox | label, name or CSS selector |
| Checkbox shouldn't be checked | is_not_checked | checkbox | label, name or CSS selector |
| Radio button should be selected | radio_selected | radio | name of the radio button |
| Dropdown with name should be selected | dropdown_selected | select, option | select: label, name or CSS selector, option: content, value or CSS selector |
| Dropdown with name shouldn't be selected | dropdown_not_selected | select, option | select: label, name or CSS selector, option: content, value or CSS selector |
Example steps
"steps": [
{
"fn": "go_to",
"args": {
"url": "pingdom.com"
}
},
{
"fn": "click",
"args": {
"element": "START FREE TRIAL"
}
},
{
"fn": "url",
"args": {
"url": "https://www.pingdom.com/sign-up/"
}
}
]
Recording transaction checks
Each of check steps contains:
fn: function name of the step args: function arguments guid: automatically generated identifier contains_navigate: recorder sets it on true if the step would trigger a page navigation
Commands
Actions to be performed for the recording TMS check
| Step Name | "fn" | Required "args" | Remarks |
|---|---|---|---|
| Go to URL | wpm_go_to | url | Goes to the given url location |
| Click | wpm_click | element, offsetX, offsetY | element: label, name or CSS selector, offsetX/Y: exact position of a click in the element |
| Click in a exact location | wpm_click_xy | element, x, y, scrollX, scrollY | element: label, name or CSS selector, x/y: coordinates for the click (in viewport), scrollX/Y: scrollbar position |
| Fill | wpm_fill | input, value | input: target element, value: text to fill the target |
| Move mouse to element | wpm_move_mouse_to_element | element, offsetX, offsetY | element: target element, offsetX/Y: exact position of the mouse in the element |
| Select dropdown | wpm_select_dropdown | select, option | select: target element (drop-down), option: text of the option to select |
| Wait | wpm_wait | seconds | seconds: numbers of seconds to wait |
| Close tab | wpm_close_tab | - | Closes the latest tab on the tab stack |
Validations
Verify the state of the page
| Step Name | "fn" | Required "args" | Remarks |
|---|---|---|---|
| Contains text | wpm_contains_timeout | element, value, waitTime, useRegularExpression | element: label, name or CSS selector, value: text to search for, waitTime: time to wait for the value to appear, useRegularExpression: use the value as a RegEx |
| Does not contains text | wpm_not_contains_timeout | element, value, waitTime, useRegularExpression | element: label, name or CSS selector, value: text to search for, waitTime: time to wait for the value to appear, useRegularExpression: use the value as a RegEx |
Metadata
Recording checks contain metadata which is automatically generated by the WPM recorder. Modify with caution!
create_alerting_contact
Creates a new contact with at least one contact method (notification target)
Parameters
$body
Type: object
{
"paused" : "Pause contact",
"name" : "Contact name",
"notification_targets" : { }
}
create_alerting_team
Creates a new team with or without members
Parameters
$body
Type: object
{
"member_ids" : [ "integer" ],
"name" : "Team name"
}
create_check
Creates a new check with settings specified by provided parameters.
Parameters
$body
Type: object
{
"encryption" : "Connection encryption",
"port" : "Target port",
"requestheaders" : [ "string" ],
"shouldnotcontain" : "Target site should NOT contain this string. Note! This parameter cannot be used together with the parameter “shouldcontain”, use only one of them in your request.",
"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",
"shouldcontain" : "Target site should contain this string. Note! This parameter cannot be used together with the parameter “shouldnotcontain”, use only one of them in your request.",
"url" : "Path to target on server",
"ssl_down_days_before" : "Treat the target site as down if a certificate expires within the given number of days. This parameter will be ignored if `verify_certificate` is set to `false`.",
"verify_certificate" : "Treat target site as down if an invalid/unverifiable certificate is found."
}
create_maintenance
Create new maintenance window.
Parameters
$body
Description
Type: object
{
"effectiveto" : "Recurrence end. Format UNIX time. Default: equal to `to`. (Only future allowed. Use 1 for the current timestamp.)",
"tmsids" : [ "integer" ],
"description" : "Description",
"uptimeids" : [ "integer" ],
"from" : "Initial maintenance window start. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.)",
"to" : "Initial maintenance window end. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.)",
"repeatevery" : "Repeat every n-th day/week/month",
"recurrencetype" : "Type of recurrence."
}
create_tm_check
Creates a new transaction check.
Parameters
$body
Specifies the check to be added
Type: object
{
"metadata" : {
"disableWebSecurity" : "Setting this field to false will disable the same-origin policy during check execution",
"width" : "Width of the browser window",
"height" : "Height of the browser window",
"authentications" : {
"httpAuthentications" : [ {
"credentials" : {
"password" : "Basic Authentication password",
"userName" : "Basic Authentication Username"
},
"host" : "string"
} ]
}
},
"send_notification_when_down" : "Send notification when down X times",
"team_ids" : [ "integer" ],
"active" : "Check status: active or inactive",
"severity_level" : "Check importance- how important are the alerts when the check fails. Allowed values: low, high",
"contact_ids" : [ "integer" ],
"steps" : [ {
"args" : {
"input" : "string",
"password" : "string",
"seconds" : "string",
"select" : "string",
"form" : "string",
"checkbox" : "string",
"value" : "string",
"url" : "string",
"element" : "string",
"option" : "string",
"radio" : "string",
"username" : "string"
},
"fn" : "Operation to be done"
} ],
"integration_ids" : [ "integer" ],
"tags" : [ "string" ],
"custom_message" : "Custom message that is part of the email and webhook alerts",
"name" : "Name of the check",
"interval" : "TMS test intervals in minutes. Allowed intervals: 5,10,20,60,720,1440. The interval you're allowed to set may vary depending on your current plan.",
"region" : "Name of the region where the check is executed. Supported regions: us-east, us-west, eu, au"
}
delete_alerting_contact
Deletes a contact with its contact methods (notification targets)
Parameters
contactid (required)
ID of contact to be deleted
Type: integer
delete_alerting_team
Deletes a team
Parameters
teamid (required)
ID of the team to be deleted
Type: integer
delete_check
Deletes a list of checks. THIS METHOD IS IRREVERSIBLE! You will lose all collected data. Be careful!
Parameters
delcheckids (required)
Comma-separated list of identifiers for checks to be deleted.
Type: array
[ "integer" ]
delete_checks
Deletes a check. THIS METHOD IS IRREVERSIBLE! You will lose all collected data. Be careful!
Parameters
checkid (required)
Identifier of check to be deleted
Type: integer
delete_maintenance
Delete the maintenance window. Note that only future maintenance window can be deleted.
Parameters
id (required)
id of maintenance window
Type: integer
delete_maintenance_occurrence
Deletes the maintenance occurrence specified by its identifier. Note that only future occurrences can be deleted.
Parameters
id (required)
Type: integer
delete_maintenance_occurrences
Deletes multiple maintenance occurrences specified by their identifiers. Note that only future occurrences can be deleted.
Parameters
occurenceids (required)
Type: object
{
"occurrenceids" : [ "integer" ]
}
delete_maintenances
Delete multiple maintenance windows. Note that only future maintenance windows can be deleted.
Parameters
maintenanceids (required)
Comma-separated list of identifiers of maintenance windows to be deleted.
Type: array
[ "integer" ]
delete_tm_check
Deletes a transaction check.
Parameters
cid (required)
Specifies the id of the check to be deleted
Type: integer
get_alerting_contact
Returns a contact with its contact methods (notification targets)
Parameters
contactid (required)
ID of contact to be retrieved
Type: integer
get_alerting_team
Returns a team with its members
Parameters
teamid (required)
ID of the team to be retrieved
Type: integer
get_analysis_check
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.
Parameters
analysisid (required)
Type: integer
checkid (required)
Type: integer
get_check
Returns a detailed description of a specified check.
Parameters
checkid (required)
Identifier of check to be retrieved
Type: integer
include_teams
Include team connections for check.
Type: boolean
get_credit
Returns information about remaining checks, SMS credits and SMS auto-refill status.
This operation has no parameters
get_maintenance
Returns the maintenance window specified by its id.
Parameters
id (required)
id of maintenance window
Type: integer
get_maintenance_occurrence
Gets a maintenance occurrence details specified by its identifier.
Parameters
id (required)
Type: integer
get_reference
Get a reference of regions, timezones and date/time/number formats and their identifiers.
This operation has no parameters
get_summary_average
Get the average time / uptime value for a specified check and time period.
Parameters
checkid (required)
Type: integer
bycountry
Split response times into country groups
Type: boolean
byprobe
Split response times into probe groups
Type: boolean
from
Start time of period. Format is UNIX timestamp
Type: integer
includeuptime
Include uptime information
Type: boolean
probes
Filter to only use results from a list of probes. Format is a comma separated list of probe identifiers. By default result from all probes are shown.
Type: string
to
End time of period. Format is UNIX timestamp. Default is the current time
Type: integer
get_summary_hoursofday
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.
Parameters
checkid (required)
Type: integer
from
Start time of period. Format is UNIX timestamp. Default value is one week eariler than to.
Type: integer
probes
Filter to only use results from a list of probes. Format is a comma separated list of probe identifiers. By default all probes results are returned.
Type: string
to
End time of period. Format is UNIX timestamp. Default value is current time.
Type: integer
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.
Type: boolean
get_tm_check
Returns a single transaction check.
Parameters
cid (required)
Specifies the id of the check to be fetched
Type: integer
extended_tags
Specifies whether to return an extended tags representation in the response (with type and count).
Type: boolean
get_tm_check_report_performance
For a given period of time, return a list of time intervals with the given resolution. An interval may be a week, a day or an hour depending on the chosen resolution. It can be used to display a detailed view of a check with information about its steps and generate graphs.
Parameters
check_id (required)
Specifies the id of the check for which the performance report will be fetched
Type: integer
from
Start time of period. The format is RFC 3339 (properly URL-encoded!). The default value is 10 times the resolution (10 hours, 10 day, 10 weeks) earlier than to. The value is extended to the nearest hour, day or week, depending on the 'resolution' parameter and configured time zone of the account.
Type: date-time
include_uptime
Include uptime information. Adds field downtime, uptime, and unmonitored to the interval array objects.
Type: boolean
order
Sorting order of outages. Ascending or descending
Type: string
Potential values: asc, desc
resolution
Size of an interval for which the results are calculated. For the hour resolution, the max allowed period is one week and 1 day. For the day resolution, the max allowed period is 6 months and 1 day.
Type: string
Potential values: hour, day, week
to
End time of period. The format is RFC 3339 (properly URL-encoded!). The default value is the current time. The value is extended to the nearest hour, day or week, depending on the 'resolution' parameter and configured time zone of the account.
Type: date-time
get_tm_check_report_status
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. (The default is ordered by oldest first.) It can be used to display a detailed view of a check.
Parameters
check_id (required)
Specifies the id of the check for which the status change report will be fetched
Type: integer
from
Start time of period. The format is RFC 3339 (properly URL-encoded!). The default value is one week earlier than to
Type: date-time
order
Sorting order of outages. Ascending or descending
Type: string
Potential values: asc, desc
to
End time of period. The format is RFC 3339 (properly URL-encoded!). The default value is the current time
Type: date-time
get_tm_check_report_statuses
Get a list of status changes for all transaction check in the current organization from the requested time period. If order is speficied to descending, the list of statuses within each check is ordered by newest first. (The default is ordered by oldest first.) It can be used to display a list view of all checks and their current status.
Parameters
from
Start time of period. The format is RFC 3339 (properly URL-encoded!). The default value is one week earlier than to
Type: date-time
limit
Limit of returned checks
Type: string
offset
Offset of returned checks
Type: string
omit_empty
Omits checks without any results within specified time
Type: boolean
order
Sorting order of outages. Ascending or descending
Type: string
Potential values: asc, desc
to
End time of period. The format is RFC 3339 (properly URL-encoded!). The default value is the current time
Type: date-time
get_traceroute
Perform a traceroute to a specified target from a specified Pingdom probe.
Parameters
host (required)
Target host.
Type: string
probeid
Probe identifier.
Type: integer
list_actions
Returns a list of actions (alerts) that have been generated for your account.
Parameters
checkids
Comma-separated list of check identifiers. Limit results to actions generated from these checks. Default: all checks.
Type: string
from
Only include actions generated later than this timestamp. Format is UNIX time.
Type: integer
limit
Limits the number of returned results to the specified quantity.
Type: integer
offset
Offset for listing.
Type: integer
status
Comma-separated list of statuses. Limit results to actions with these statuses. Default: all statuses.
Type: string
to
Only include actions generated prior to this timestamp. Format is UNIX time.
Type: integer
userids
Comma-separated list of user identifiers. Limit results to actions sent to these users. Default: all users.
Type: string
via
Comma-separated list of via mediums. Limit results to actions with these mediums. Default: all mediums.
Type: string
list_alerting_contacts
Returns a list of all contacts with their contact methods (notification targets)
This operation has no parameters
list_alerting_teams
Returns a list of all teams and their members
This operation has no parameters
list_analyses
Returns a list of the latest root cause analysis results for a specified check.
Parameters
checkid (required)
Type: integer
from
Return only results with timestamp of first test greater or equal to this value. Format is UNIX timestamp.
Type: integer
limit
Limits the number of returned results to the specified quantity.
Type: integer
offset
Offset for listing. (Requires limit.)
Type: integer
to
Return only results with timestamp of first test less or equal to this value. Format is UNIX timestamp. Default: current timestamp
Type: integer
list_checks
Returns a list overview of all checks.
Parameters
include_severity
Include severity level for each check.
Type: boolean
include_tags
Include tag list for each check. Tags can be marked as "a" or "u", for auto tagged or user tagged.
Type: boolean
limit
Limits the number of returned probes to the specified quantity. (Max value is 25000)
Type: integer
offset
Offset for listing. (Requires limit.)
Type: integer
showencryption
If set, show encryption setting for each check
Type: boolean
tags
Tag list separated by commas. As an example "nginx,apache" would filter out all responses except those tagged nginx or apache
Type: string
list_maintenance_occurrences
Returns a list of maintenance occurrences.
Parameters
from
Effective from (unix timestamp). (List occurrences which are effective from the specified unix timestamp. If not specified, current timestamp is used.)
Type: integer
maintenanceid
Maintenance window identifier. (List only occurrences of a specific maintenance window.)
Type: integer
to
Effective to (unix timestamp). (List occurrences which are effective to the specified unix timestamp.)
Type: integer
list_maintenances
Returns a list of user's maintenance windows.
Parameters
limit
Count of items to list.
Type: integer
offset
Offset of the list.
Type: integer
order
Order a-z for asc z-a for desc. Works only if orderby is specified.
Type: string
Potential values: asc, desc
orderby
Order by the specific property of the maintenance window.
Type: string
Potential values: description, from, to, effectiveto
list_probes
Returns a list of all Pingdom probe servers for Uptime and Transaction checks.
Parameters
includedeleted
Include old probes that are no longer in use.
Type: boolean
limit
Limits the number of returned probes to the specified quantity.
Type: integer
offset
Offset for listing. (Requires limit.)
Type: integer
onlyactive
Return only active probes.
Type: boolean
list_results
Return a list of raw test results for a specified check
Parameters
checkid (required)
Type: integer
from
Start of period. Format is UNIX timestamp. Default value is 1 day prior to to.
Type: integer
includeanalysis
Attach available root cause analysis identifiers to corresponding results
Type: boolean
limit
Number of results to show (Will be set to 1000 if the provided value is greater than 1000)
Type: integer
maxresponse
Maximum response time (ms). If set, specified interval must not be larger than 31 days.
Type: integer
minresponse
Minimum response time (ms). If set, specified interval must not be larger than 31 days.
Type: integer
offset
Number of results to skip (Max value is 43200)
Type: integer
probes
Default: all probes
Type: string
status
Default: all statuses
Type: string
to
End of period. Format is UNIX timestamp. Default value is current timestamp.
Type: integer
list_summary_outages
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.)
Parameters
checkid (required)
Type: integer
from
Start time of period. Format is UNIX timestamp. Default value is one week earlier than to.
Type: integer
order
Sorting order of outages. Ascending or descending.
Type: string
Potential values: asc, desc
to
End time of period. Format is UNIX timestamp. Default value is the current time.
Type: integer
list_summary_performances
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.
Parameters
checkid (required)
Type: integer
from
Start time of period. Format is UNIX timestamp. Default value is 10 intervals earlier than to.
Type: integer
includeuptime
Include uptime information.
Type: boolean
order
Sorting order of sub intervals. Ascending or descending.
Type: string
Potential values: asc, desc
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. By deafult results from all probes are returned.
Type: string
resolution
Interval size
Type: string
Potential values: hour, day, week
to
End time of period. Format is UNIX timestamp. Default value is the current time.
Type: integer
list_summary_probes
Get a list of probes that performed tests for a specified check during a specified period.
Parameters
checkid (required)
Type: integer
from (required)
Start time of period. Format is UNIX timestamp
Type: integer
to
End time of period. Format is UNIX timestamp. The defualt value is current time.
Type: integer
list_tm_checks
Returns a list overview of all transaction checks.
Parameters
extended_tags
Specifies whether to return an extended tags representation in the response (with type and count).
Type: boolean
limit
Limit of returned checks
Type: string
offset
Offset of returned checks
Type: string
tags
Tag list separated by commas. As an example "nginx,apache" would filter out all responses except those tagged nginx or apache
Type: array
[ "string" ]
type
Filter to return only checks of a given type (a TMS script or a WPM recording). If not provided, all checks are returned.
Type: string
Potential values: script, recording
perform_single_check
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.
Parameters
Query Parameters
Query Parameters to chose
Type: object
{
"auth" : "(http specific) Username and password for target HTTP authentication.",
"probeid" : "Probe identifier",
"ssl_down_days_before" : "(http specific) Treat the target site as down if a certificate expires within the given number of days. This parameter will be ignored if `verify_certificate` is set to `false`.",
"type" : "Required string. Possible values: http",
"shouldnotcontain" : "(http specific) Target site should NOT contain this string",
"postdata" : "(http specific) 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",
"responsetime_threshold" : "Triggers a down alert if the response time exceeds threshold specified in ms (Not available for Starter and Free plans.)",
"shouldcontain" : "(http specific) Target site should contain this string",
"url" : "(http specific) Target path on server",
"encryption" : "(http specific) Connection encryption",
"port" : "(http specific) Target port",
"requestheader{X}" : "(http specific) Custom HTTP header name. Replace {X} with a number unique for each header argument.",
"ipv6" : "Use ipv6 instead of ipv4",
"host" : "Target host",
"probe_filters" : "Filters used for probe selections. Comma separated key:value pairs. Currently only region is supported. Possible values are 'EU', 'NA', 'APAC' and 'LATAM'.",
"verify_certificate" : "(http specific) Treat target site as down if an invalid/unverifiable certificate is found."
}
update_alerting_contact
Update a contact with at least one contact method (notification target)
Parameters
contactid (required)
ID of contact to be updated
Type: integer
$body
Type: object
{
"paused" : "Pause contact",
"name" : "Contact name",
"notification_targets" : { }
}
update_alerting_team
Updates a team
Parameters
teamid (required)
ID of the team to be retrieved
Type: integer
$body
Type: object
{
"member_ids" : [ "integer" ],
"name" : "Team name"
}
update_check
Modify settings for a check. The provided settings will overwrite previous values. Settings not provided will stay the same as before the update. To clear an existing value, provide an empty value. Please note that you cannot change the type of a check once it has been created.
Parameters
checkid (required)
Identifier of check to be updated
Type: integer
$body
Type: object
{
"encryption" : "Connection encryption",
"port" : "Target port",
"requestheaders" : [ "string" ],
"shouldnotcontain" : "Target site should NOT contain this string. Note! This parameter cannot be used together with the parameter “shouldcontain”, use only one of them in your request.",
"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",
"shouldcontain" : "Target site should contain this string. Note! This parameter cannot be used together with the parameter “shouldnotcontain”, use only one of them in your request.",
"url" : "Path to target on server",
"ssl_down_days_before" : "Treat the target site as down if a certificate expires within the given number of days. This parameter will be ignored if `verify_certificate` is set to `false`.",
"verify_certificate" : "Treat target site as down if an invalid/unverifiable certificate is found."
}
update_checks
Pause or change resolution for multiple checks in one bulk call.
Parameters
$body
Type: object
{
"paused" : "Use value: true to pause the check(s) and value: false to unpause it(them).",
"checkids" : "Comma-separated list of identifiers for checks to be modified. Invalid check identifiers will be ignored. Default: all checks\n",
"resolution" : "integer. Possible values: 1 | 5 | 15 | 30 | 60"
}
update_maintenance
Modify the maintenance window.
Parameters
id (required)
id of maintenance window
Type: integer
$body
Description
Type: object
{
"effectiveto" : "Recurrence end. Format UNIX time. Default: equal to `to`. (Only future allowed. Use 1 for the current timestamp.)",
"tmsids" : [ "integer" ],
"description" : "Description",
"uptimeids" : [ "integer" ],
"from" : "Initial maintenance window start. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.)",
"to" : "Initial maintenance window end. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.)",
"repeatevery" : "Repeat every n-th day/week/month",
"recurrencetype" : "Type of recurrence"
}
update_maintenance_occurrence
Modifies a maintenance occurrence specified by its identifier.
Parameters
id (required)
Type: integer
$body
Type: object
{
"from" : "Beginning of the maintenance occurrence. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.)",
"to" : "End of the maintenance occurrence. Format UNIX time. (Only future allowed. Use 1 for the current timestamp.)"
}
update_tm_check
Modify settings for transaction check.
Parameters
cid (required)
Specifies the id of the check to be modified
Type: integer
$body
Specifies the data to be modified for the check
Type: object
{
"metadata" : {
"disableWebSecurity" : "Setting this field to false will disable the same-origin policy during check execution",
"width" : "Width of the browser window",
"height" : "Height of the browser window",
"authentications" : {
"httpAuthentications" : [ {
"credentials" : {
"password" : "Basic Authentication password",
"userName" : "Basic Authentication Username"
},
"host" : "string"
} ]
}
},
"send_notification_when_down" : "Send notification when down X times",
"team_ids" : [ "integer" ],
"active" : "Check status: active or inactive",
"severity_level" : "Check importance- how important are the alerts when the check fails. Allowed values: low, high",
"contact_ids" : [ "integer" ],
"steps" : [ {
"args" : {
"input" : "string",
"password" : "string",
"seconds" : "string",
"select" : "string",
"form" : "string",
"checkbox" : "string",
"value" : "string",
"url" : "string",
"element" : "string",
"option" : "string",
"radio" : "string",
"username" : "string"
},
"fn" : "Operation to be done"
} ],
"tags" : [ "string" ],
"integration_ids" : [ "integer" ],
"custom_message" : "Custom message that is part of the email and webhook alerts",
"name" : "Name of the check",
"interval" : "TMS test intervals in minutes. Allowed intervals: 5,10,20,60,720,1440. The interval you're allowed to set may vary depending on your current plan.",
"region" : "Name of the region where the check is executed. Supported regions: us-east, us-west, eu, au"
}