The Uptrends API allows you to modify monitor and monitor group information directly in your Uptrends account. The API is a web service that uses a REST interface to perform basic CRUD (Create, Read, Update, Delete) operations on Uptrends entities.
It also lets you retrieve the data from your account. This includes the current status of your monitors, statistics of the performance of your monitors and monitor groups, and the alerts history of your monitors.
Prerequisites
To use the Uptrends API you need the following:
- The username and password of an Uptrends account, or the login credentials of an operator in that account.
- Access to the API domain located at: https://api.uptrends.com/v3
Accessing the API
The API can be accessed at the specified base URL using the HTTPS protocol.
Authentication
The API requires HTTP Basic Authentication to get access to the information. You need an Uptrends login name and password to get access.
The login name you use can be the main login for your Uptrends account, or any operator you create in the account. Please note that you will need to use an administrator account (i.e. an operator that is a member of the Administrators group) if you want to perform updates.
HTTP methods
Based on the HTTP method the following actions are supported:
| Operation | Comments | Http Return Code |
|---|---|---|
| GET | Retrieve an item | 200 (HTTP OK) |
| POST | Create an item | 201 (HTTP CREATED) |
| PUT | Update an item | 200 (HTTP OK) |
| DELETE | Remove an item | 200 (HTTP OK) |
Error handling
When an error occurs, an HTTP error code 400 (Bad Request) is returned with an error description in the response content.
The API supports the transfer of data in the following formats:
| Data format | Http Content-type | Override URL parameter |
|---|---|---|
XML | application/xml | ?format=xml |
JSON | application/json | ?format=json To embed the response in a jsonp callback append ?callback=myCallback |
JSV | text/jsv | ?format=jsv |
CSV | text/csv | ?format=csv |
SOAP 1.1 | application/xml | ?format=soap11 |
SOAP 1.2 | application/xml | ?format=soap12 |
Format
Some API operations return DateTime data. The format of that data will be according to the ISO 8601 standard, but without timezone information. The data will be expressed as a local date and time, with respect to the timezone that has been set in the Uptrends account settings.
Example:
A date and time of June 1st, 2015 at 09:35:59 PM will be expressed as:
2015-06-01T21:35:59
regardless of the timezone in your account settings. If your timezone is EST (UTC -05:00), this value should be interpreted as June 1st, 2015 09:35:59 PM, EST.
API Operations
All operations can be performed on the following base URL:
Base URL: https://api.uptrends.com/v3/<operation url>
- Example 1: the following URL gives a list of all monitor groups in your account:
https://api.uptrends.com/v3/probegroups - Example 2: To update the name of a monitor group, perform a HTTP PUT to the following URL
https://api.uptrends.com/v3/probegroups/688b2eab-f650-45e6-80f2-0158273d8257
The request body should then contain JSON or XML data with the following content:
{"Name":"Updated ProbeGroupName"}
For updates, you only need to provide the fields you want to modify. Fields omitted from the request will remain unchanged.
Monitor operations
| Operation | Method | URL | Return value |
|---|---|---|---|
| List all monitors | GET | /probes | List<Probe> |
| Create monitor | POST | /probes | Probe |
| Get monitor | GET | /probes/{ProbeGuid} | Probe |
| Update monitor | PUT | /probes/{ProbeGuid} | (empty) |
| Delete monitor | DELETE | /probes/{ProbeGuid} | (empty) |
Field definition: Probe
| Field name | Type | Comments |
|---|---|---|
Guid | Guid | Unique monitor ID |
Name | String | Name of the monitor |
URL | String | URL or IP address of the website, (web/database/mail/FTP/DNS-) server to check. |
Port | Integer | Port number |
CheckFrequency | Integer | Time interval between individual checks, in minutes. Typically this is set to 5. Using a value lower than the minimum frequency for the account (also typically 5) returns an error. |
ProbeType | Enumeration | Allowed values: Http, Https, Connect, Ping, POP3, SMTP, IMAP, FTP, MySQL, MSSQL, WebserviceHttp, WebserviceHttps, DNS, FullPageCheck Note: the monitor type Transaction is not supported. Please use APIv4 instead. |
IsActive | Boolean | Indicates whether the monitor is active. Inactive monitors are not measured. Allowed values: True, False |
GenerateAlert | Boolean | Indicates whether to send alerts for this monitor. Allowed values: True, False |
Notes | String | User-defined notes. This value is only displayed in the Uptrends application. |
PerformanceLimit1 | Integer | First load time limit in milliseconds. |
PerformanceLimit2 | Integer | Second load time limit in milliseconds. |
ErrorOnLimit1 | Boolean | Indicates whether to generate errors when PerformanceLimit1 is exceeded. Allowed values: True, False |
ErrorOnLimit2 | Boolean | Indicates whether to generate errors when PerformanceLimit2 is exceeded. Allowed values: True, False |
MinBytes | Integer | The minimum number of bytes in the server response to check for. |
ErrorOnMinBytes | Boolean | Indicates whether to generate errors when MinBytes is exceeded. Allowed values: True, False |
Timeout | Integer | The time limit for the complete test, in milliseconds. |
TcpConnectTimeout | Integer | The time limit for the initial TCP connection, in milliseconds. |
MatchPattern | String | Content to check for in the response of HTTP requests. Regular expressions are allowed. |
UserAgent | String | The user agent (browser identification value) to specify for HTTP(S) and Full Page Check monitors. |
UserName | String | The username to specify as Basic/Digest/NTLM Authentication (when available), or the login name for FTP, FTPS or SQL monitors. |
Password | String | The password to specify as Basic/Digest/NTLM Authentication (when available), or the password for FTP, FTPS or SQL monitors. Please note that the password field will always be empty when you retrieve data - you can only use this field when you specify a password. |
Checkpoints | String | An enumeration of checkpoints to use for this monitor. To use all checkpoints, specify an empty value. To use specific checkpoints, list the checkpoint IDs separated by a comma, e.g.: 1,2,15,27 Note: when specifying specific checkpoints, select at least two checkpoints. |
UseOnlyPrimaryCheckpoints | Boolean | Indicates whether Uptrends should limit the checkpoints you specify to primary checkpoints only. Uptrends defaults to True to limit the checkpoints to primary. To allow your monitor to run on non-primary checkpoint locations as well, specify False. Please note: Due to technical limitations and other circumstances beyond Uptrends' control, non-primary checkpoints may suffer from reduced availability, poor bandwidth, and unpredictable connectivity. Please use this option only if you explicitly need monitoring from these locations and can accept results that are not always consistent. |
|
|
|
Specific values for DNS monitors: |
|
|
DNSQueryType | Enumeration | The type of DNS query. Allowed values: ARecord, CNAMERecord, MXRecord, NSRecord, TXTRecord |
DNSTestValue | String | The value to query for a DNS monitor. For example, when checking an A record, this value contains the domain name to check. |
DNSExpectedResult | String | The expected result of the DNS query. Regular expressions are allowed. |
|
|
|
Specific values for Database monitors: |
|
|
DatabaseName | String | |
|
|
|
Specific values for HTTP(S) and WebserviceHTTP(S) monitors: |
|
|
HttpMethod | Enumeration | Allowed values: Get, Post |
PostData | String | Content for the request body in case of a Post request. |
|
|
|
Specific values for Connect monitors: |
|
|
ConnectMethod | Enumeration | Allowed values: Tcp, Udp |
Example
To add a DNS monitor to the account, send a POST request to https://api.uptrends.com/v3/probes, provide the necessary Basic Authentication, set the Content-Type and Accept headers to application/json and provide the following content as the request body:
{ "Name":"DNS Test monitor", "URL":"NS81.WORLDNIC.com", "Port":53, "CheckFrequency":5, "ProbeType":"DNS", "IsActive":true, "GenerateAlert":false, "Notes":"", "PerformanceLimit1":2500, "PerformanceLimit2":5000, "ErrorOnLimit1":false, "ErrorOnLimit2":false, "Timeout":30000, "TcpConnectTimeout":10000, "IsCompetitor":false, "Checkpoints":"1,8,28", "DNSQueryType":"MXRecord", "DNSTestValue":"uptrends.com", "DNSExpectedResult":"smtp.uptrends.com" }
Monitor group operations
| Operation | Method | URL | Return value |
|---|---|---|---|
| List all monitor groups | GET | /probegroups | List<ProbeGroup> |
| Create monitor group | POST | /probegroups | ProbeGroup |
| Get monitor group | GET | /probegroups/{ProbeGroupGuid} | ProbeGroup |
| Update monitor group | PUT | /probegroups/{ProbeGroupGuid} | (empty) |
| Delete monitor group | DELETE | /probegroups/{ProbeGroupGuid} | (empty) |
Field definition: ProbeGroup
| Field name | Type | Comments |
|---|---|---|
| Guid | Guid | Unique monitor group ID |
| Name | String | Name of the monitor group |
Example 1
To get a list of all monitor groups, perform a GET request to /probegroups. The response body contains a list of probe groups:
[ { "Guid" : "680a5071c6d645a3b56945053b2d6a90", "Name" : "All probes" }, { "Guid" : "b1d9f5451aa04600992dc02d36f80e40", "Name" : "Probe group 1" }, { "Guid" : "25532138344a407597ad679ba1176aae", "Name" : "My other probe group" }, { "Guid" : "939110bb5d514dfe95e553b8a7dc8cde", "Name" : "Test probe group" } ]
Example 2
To create a new group, perform a POST request to /probegroups. The request body should specify the name for the new group:
{"Name":"My new group"}
The response body will contain the new group:
{"Guid":"bd6e2c7e8a2348dc88206460d73f3658","Name":" My new group "}
Monitor group member operations
The following methods operate on monitor group membership, i.e. which monitors are part of which groups.
| Operation | Method | URL | Return value |
|---|---|---|---|
| List all monitors in a group | GET | /probegroups/{ProbeGroupGuid}/members | List<Probe> |
| Add monitor to a group | POST | /probegroups/{ProbeGroupGuid}/members | {Guid, ProbeGuid} |
| Remove monitor from a group | DELETE | /probegroups/{ProbeGroupGuid}/members | (empty) |
Example 1
To get all monitors in a monitor group, send a GET request to /probegroups/{ProbeGroupGuid}/members. The response body will contain a list of monitors. (data in this example shortened for brevity):
[ { "Guid" : "f1248efda52e4d8db6ac6431a4a19177", "Name" : "Test probe 1", "URL" : "https://www.uptrends.com", "Port" : 80, }, { "Guid" : "a339b142-5a87-4a18-a718-00d679a13f5d", "Name" : "Test probe 2", "URL" : "https://www.uptrends.com", "Port" : 443, } ]
Example 2
To add a monitor to a group, send a POST request to /probegroups/{ProbeGroupGuid}/members. The request body should contain a reference to the monitor Guid being added to the group:
{ "ProbeGuid" : "c4c8f5df7d02410bb1a837ce24bb2e8b" }
Listing checkpoint servers
The following operation returns a list of Uptrends’ checkpoint servers. This information can be used for two things:
- The CheckpointID values should be used when specifying specific checkpoints for a monitor.
- The list contains the IP addresses for each checkpoint server. Please note that one checkpoint can have multiple checkpoint servers, and therefore multiple IP addresses.
| Operation | Method | URL | Return value |
|---|---|---|---|
| List all checkpoint servers | GET | /checkpointservers | List<CheckpointServer> |
Field definition: CheckpointServer
| Field name | Type | Comments |
|---|---|---|
| CheckPointID | Integer | Unique ID for the checkpoint. Use this value for specifying checkpoints for a monitor. |
| ServerID | Integer | Only used to make the combination of CheckPointID and IP address unique. Do not use this value. |
| CheckPointName | String | Contains the city and country where the checkpoint server is located. |
| IPAddress | String | The IP address of the checkpoint server. |
Example
To retrieve the list of checkpoint servers, perform a GET request to /checkpointservers. The response body contains a list of checkpoints (data in this example shortened for brevity). Please note that the London checkpoint in this example (CheckpointID = 1) has two IP addresses.
[ { "ServerID" : 0, "CheckPointID" : 0, "CheckPointName" : "Amsterdam, The Netherlands", "IPAddress" : "81.18.240.134" }, { "ServerID" : 10, "CheckPointID" : 1, "CheckPointName" : "London, United Kingdom", "IPAddress" : "81.89.133.149" }, { "ServerID" : 11, "CheckPointID" : 1, "CheckPointName" : "London, United Kingdom", "IPAddress" : "109.73.162.168" }, { "ServerID" : 20, "CheckPointID" : 2, "CheckPointName" : "Austin, TX, USA", "IPAddress" : "216.139.219.45" }, { "ServerID" : 30, "CheckPointID" : 3, "CheckPointName" : "Sydney, Australia", "IPAddress" : "202.51.170.6" }, { "ServerID" : 40, "CheckPointID" : 4, "CheckPointName" : "Tampa, FL, USA", "IPAddress" : "66.230.202.37" } ]
Getting current monitor status
The following operations return one or more monitors and their current monitoring status.
| Operation | Method | URL | Return value |
|---|---|---|---|
| List status of all monitors in group | GET | /probegroups/{ProbeGroupGuid}/status | List<Status> |
| Status of a single monitor | GET | /probes/{ProbeGuid}/status | Status |
Field definition: Status
| Field name | Type | Comments |
|---|---|---|
| ProbeGuid | Guid | Unique ID for the monitor. |
| ErrorLevel | Enumeration | Values: NoError, Unconfirmed, Confirmed |
| ErrorDescription | String | Description of the current error for this monitor, or “OK” if there is no error. |
| LastCheck | DateTime | The timestamp of the last check that was performed for this monitor. |
| CheckPointID | Integer | The ID of the checkpoint server that performed the last check. |
| Uptime | Float | Uptime for this monitor, for the last 24 hours. |
Example
To retrieve the status for a group of monitors, perform a GET request to /probegroups/{probegroupguid}/status. The response body contains a list of status objects.
[ { "ProbeGuid" : "2a1d74876f8247139c731e9b4dce203b", "ErrorLevel" : "NoError", "LastCheck" : "2015-06-07T08:56:18", "CheckPointID" : 36 }, { "ProbeGuid" : "fa15240ae9474cff8f3e6488678627fe", "ErrorLevel" : "Confirmed", "LastCheck" : "2015-06-07T08:58:18", "CheckPointID" : 33 }, { "ProbeGuid" : "b142467ed373f5c18f0d68d16850952f", "ErrorLevel" : "NoError", "LastCheck" : "2015-06-07T08:59:45", "CheckPointID" : 55 }, { "ProbeGuid" : "ed2a88cd280b404aab9a9167ddc5ddb0", "ErrorLevel" : "NoError", "LastCheck" : "2015-06-07T08:56:18", "CheckPointID" : 18 } ]
Getting statistics for monitor groups and monitors
The following operation returns statistical data (including uptime, load times, etc.; see below) for the requested monitors, for a specified time period.
| Operation | Method | URL | Return value |
|---|---|---|---|
List statistical data for a group | GET | /probegroups/{ProbeGroupGuid}/statistics? Start=<startdate>&End=<enddate>&Dimension=<dimension> Start: start date for the requested time period, formatted as yyyy/mm/dd End: end date for the requested time period, formatted as yyyy/mm/dd. The end date is not included in the result. Dimension: how to group/aggregate the results. Possible values: Day, Week, Month, Year, ProbeGroup, Probe, Checkpoint, ErrorCode, ErrorLevel | List<Statistics> |
List statistical data for a monitor | GET | /probes/{ProbeGuid}/statistics? Start=<startdate>&End=<enddate>&Dimension=<dimension> Start: start date for the requested time period, formatted as yyyy/mm/dd End: end date for the requested time period, formatted as yyyy/mm/dd. The end date is not included in the result. Dimension: how to group/aggregate the results. Possible values: Day, Week, Month, Year, ProbeGroup, Probe, Checkpoint, ErrorCode, ErrorLevel | List<Statistics> |
Field definition: Statistics
| Field name | Type | Comments |
|---|---|---|
| ProbeGuid | Guid | Unique ID for the monitor. |
| ErrorLevel | Enumeration | Values: NoError, Unconfirmed, Confirmed |
| LastCheck | DateTime | The timestamp of the last check that was performed for this monitor. |
| CheckPointID | Integer | The ID of the checkpoint server that performed the last check. |
| Dimension | String | A value describing the dimension, according to the specified dimension in the request. Example: when a dimension ‘Month’ was specified, this field could contain “2015/01”, “2015/02”, etc. If a dimension ‘Probe’ was specified, this could contain the monitor name, etc. |
| SLAPercentage | Float | The SLA target uptime percentage |
| SLATotalTime | Float | The SLA target total load time (in seconds) |
| SLAOperatorResponseTime | Float | The SLA target operator response time (in minutes) |
| AvgOperatorResponseTime | Float | The average operator response time (in minutes) |
| PercentageOK | Float | The percentage of OK-time |
| PercentageError | Float | The percentage of Error-time |
| PercentageUnknown | Float | The percentage of time that the monitored site’s status is unknown due to pausing the monitor or while the monitor is disabled in a maintenance window. |
| PercentageUptime | Float | The percentage of Uptime |
| TotalChecks | Integer | The total number of checks |
| Errors | Integer | The total number of confirmed errors |
| UnconfirmedErrors | Integer | The total number of unconfirmed errors |
| Alerts | Integer | The number of alerts |
| SecondsOK | Integer | The total number of OK-time in seconds |
| SecondsError | Integer | The total number of Error-time in seconds |
| SecondsUnknown | Integer | The total time in seconds that the monitored site’s status is unknown due to pausing the monitor or while the monitor is disabled in a maintenance window. |
| AverageTotalTime | Float | The average total load time |
| AverageResolveTime | Float | The average resolve time |
| AverageConnectionTime | Float | The average connection time |
| AverageDownloadTime | Float | The average download time |
| AverageTotalBytes | Float | The average total number of bytes downloaded |
Example
To retrieve the status for a monitor group, for January, February and March 2015, grouped by month, perform a GET request to /probegroups/{probegroupguid}/statistics?Start=2015/01/01&End=2015/04/01&Dimension=Month.
The response body contains a list of statistics objects.
[ { "Dimension" : "2015/1", "Alerts" : 0, "SLAPercentage" : 99, "SLATotalTime" : 2, "SLAOperatorResponseTime" : 15, "AvgOperatorResponseTime" : 0, "PercentageOK" : 95.10564, "PercentageError" : 0.200337, "PercentageUnknown" : 4.694026, "PercentageUptime" : 99.79966, "TotalChecks" : 786998, "Errors" : 1473, "UnconfirmedErrors" : 36925, "SecondsOK" : 224419742, "SecondsError" : 472733, "SecondsUnknown" : 11076442, "AverageTotalTime" : 1.685304, "AverageResolveTime" : 0.004690104, "AverageConnectionTime" : 0.176703, "AverageDownloadTime" : 1.503535, "AverageTotalBytes" : 13259 }, ... ]
Getting alert history
The following operation returns a list of the alerts that were generated for the monitors in the specified probe group, during the specified time period.
| Operation | Method | URL | Return value |
|---|---|---|---|
List alert history for all monitors in group | GET | /probegroups/{ProbeGroupGuid}/alerts? Start=<startdate>&End=<enddate> Start: start date for the requested time period, formatted as yyyy/mm/dd End: end date for the requested time period, formatted as yyyy/mm/dd. The end date is not included in the result. | List<Alert> |
Field definition: Alert
| Field name | Type | Comments |
|---|---|---|
| ProbeGuid | Guid | ID that identifies the monitor for this alert |
| Timestamp | DateTime | The date and time for this alert |
| FirstError | DateTime | The date and time of the first error that triggered this alert |
| AlertType | Enumeration | Value that indicates if this is an error-alert or an OK-alert. Values: error, ok |
| ErrorDescription | String | Generic name of the type of error that occurred |
| ErrorDetails | String | When available, contains more detailed information about the error that caused this alert. For HTTP(S) monitors, this contains the description of the HTTP error. For transactions, it includes the step number and name of the step which triggered the error. |
Example
To retrieve the alert history for a group of monitors, for May 31st, 2015, perform a GET request to /probegroups/{probegroupguid}/alerts?Start=2015/05/31&End=2015/06/01
The response body contains a list of alert objects.
[ { "ProbeGuid" : "a3136b5df13740e793d428480522be7b", "Timestamp" : "2015-05-31T16:47:25", "FirstError" : "2015-05-31T16:37:50", "AlertType" : "ok" }, { "ProbeGuid" : "a3136b5df13740e793d428480522be7b", "Timestamp" : "2015-05-31T16:42:54", "FirstError" : "2015-05-31T16:37:50", "AlertType" : "error" }, { "ProbeGuid" : "a3136b5df13740e793d428480522be7b", "Timestamp" : "2015-05-31T12:41:26", "FirstError" : "2015-05-31T12:24:46", "AlertType" : "ok" } ]