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

Pingdom API (version v1.*.*)

Welcome to the Pingdom API!#

Authentication#

Basic Auth#

Server Address#

Providing Parameters#

HTTP/1.1 Status Code Definitions#

JSON Responses#

Limits#

gzip#

Best Practices#

Use caching#

Send your user credentials in a preemptive manner#

Use common sense#

The Internet is unreliable#

PHP Code Example#

TMS Steps Vocabulary#

Script transaction checks#

Commands#

Validations#

Example steps#

Recording transaction checks#

Commands#

Validations#

Metadata#

create_alerting_contact#

$body#

create_alerting_team#

$body#

create_check#

$body#

create_maintenance#

$body#

create_tm_check#

$body#

delete_alerting_contact#

contactid (required)#

delete_alerting_team#

teamid (required)#

delete_check#

delcheckids (required)#

delete_checks#

checkid (required)#

delete_maintenance#

id (required)#

delete_maintenance_occurrence#

id (required)#

delete_maintenance_occurrences#

occurenceids (required)#

delete_maintenances#

maintenanceids (required)#

delete_tm_check#

cid (required)#

get_alerting_contact#

contactid (required)#

get_alerting_team#

teamid (required)#

get_analysis_check#

analysisid (required)#

checkid (required)#

get_check#

checkid (required)#

include_teams#

get_credit#

get_maintenance#

id (required)#

get_maintenance_occurrence#

id (required)#

get_reference#

get_summary_average#

checkid (required)#

bycountry#

byprobe#

from#

includeuptime#

probes#

to#

get_summary_hoursofday#

checkid (required)#

from#

Pingdom API (version v1..)