Summary

 

GET
GET
GET
GET

/api/v1/elements/{id}/metrics
/api/v1/monitors
/api/v1/monitors /{id}
/api/v1/monitors /{id} /status


GET /api/v1/elements/{id}/metrics

Lists all metrics visible to the authenticated user account. Using the standard API format, the metrics task can be called against one Element at a time, based on ID:

GET https://youruptime/api/v1/elements/<id>/metrics/<metric>

Multiple Elements can first be filtered by the date and time of the results returned based on start and end timestamp:

GET https://youruptime/api/v1/elements/<id>/metrics/<metric>?StartDateTime=<startdatetime>&EndDateTime=<enddatetime>

Either or both StartDateTime and EndDateTime can be included. If both are included, only data points between and equal to the supplied datetimes are included. If only StartDateTime is included, only values from that point forward are included. If only EndDateTime is included, only values prior to and including are included.

Arguments

The following arguments may be passed on the call to the API:

FieldRequiredDescription
metricTypeYesThe type of metrics to return: 2 = Int; 3 = Decimal; 4 = String.
startDateTimeNoThe start time of the period for the desired metrics in the 'ddMMyyyyHHmmss' format.
endDateTimeNoThe end time of the period for the desired metrics in the 'ddMMyyyyHHmmss' format.

Returned Fields

For the returned service monitor, the following fields are provided:

FieldTypeDescription
metricDataArrayAn array listing all retained metrics for the given service monitor (see Metric Data Array below for more detail).

Metric Data Array

The metric data array returns the following attributes for each retained metric grouped by the name of the metric:

FieldTypeDescription
dataTimeString - Date TimeThe data and time when the metric was collected. 
valueInteger, Decimal, or StringThe metric value.

Response Codes

The following common response codes may result from this operation:

Other response codes that may occur include the following:

Response Code

Code Description

HTTP Status Code

Details

 OK200Information retrieved successfully.
UT-1000Element Does Not Exist404

A specifically referenced Element ID does not exist.

In such a case, referencing:

https://youruptime:9997/api/v1/elements/12345

returns the following:

The element id '12345' does not exist.

The Element ID endpoint may be omitted, was inputted incorrectly, or is ignored in Uptime Infrastructure Monitor.

UT-1010Element Filter Expired410

The referenced filter is expired. Created filters persist, by default, for five minutes.

UT-1012Element Group Filter Expired410The referenced group filter is expired. Created filters persist, by default, for five minutes.
UT-1013Invalid Element Filter400The JSON used to create an Element filter is invalid, and cannot be parsed. Check to ensure you are posting well-formed JSON.
UT-1015Invalid Element Group Filter400The JSON used to create an Element group filter is invalid, and cannot be parsed. Check to ensure you are posting well-formed JSON.
UT-1028URL ID Body Mismatch400The Element ID in the URL and the JSON object do not match.

Example

GET https://youruptime/api/v1/elements/1/metrics/1?metricType=2&startDateTime=01012015000000&endDateTime=01012015001000

{
   "metricData": {
      "Response time": [
         {"dateTime": "01012015000010", "value": "35"},
         {"dateTime": "01012015000020", "value": "120"}
      ],
      "Major": [
      {"dateTime": "01012015000010", "value": "7"},
      {"dateTime": "01012015000020", "value": "7"}
      ]
   }
}

GET /api/v1/monitors

List service monitors visible to the authenticated user account.

Returned Fields

For each returned service monitor the following fields are provided:

FieldTypeDescription
descriptionStringdescription of this service monitor
elementIdIntegerID for this service monitor's parent Element; can return a null value for unassigned monitors
idIntegerID for this Element
isHiddenBooleanhidden monitors are internal monitors that Uptime Infrastructure Monitor uses, and can be ignored
isMonitoredBooleanmonitoring status for this Element
isHostCheckBooleanreturns true if this service monitor is the host check for its parent Element
nameStringdisplay name of the service monitor
typeString

the service monitor type, typically as seen in the Uptime Infrastructure Monitor UI

Response Codes

The following common response codes may result from this operation:

Other response codes that may occur include the following:

Response Code

Code Description

HTTP Status Code

Details

 OK200Information retrieved successfully.
UT-1011Monitor Filter Expired410

The referenced filter is expired. Created filters persist, by default, for five minutes.

UT-1014Invalid Monitor Filter400The referenced Element filter does not exist.

Example

To list all service monitors:

GET https://youruptime/api/v1/monitors/

[
   {
      "description": "Collects basic performance data",
      "elementId": 1,
      "id": 3,
      "isHidden": true,
      "isHostCheck": false,
      "isMonitored": true,
      "name": "Platform Performance Gatherer",
      "type": "ERDCwindows"
   },
   {
      "description": "", 
      "elementId": 1,
      "id": 331,
      "isHidden": false,
      "isHostCheck": false,
      "isMonitored": true,
      "name": "FS-monitor-warning win-dleith",
      "type": "File System Capacity"
   },
   {
      "description": "Default uptime check for win-dleith",
      "elementId": 1,
      "id": 1,
      "isHidden": false,
      "isHostCheck": false,
      "isMonitored": true,
      "name": "UPTIME-win-dleith",
      "type": "Uptime Agent"
   },
   {
      "description": "Collects general configuration changes",
      "elementId": 1,
      "id": 4,
      "isHidden": true,
      "isHostCheck": false,
      "isMonitored": true,
      "name": "Configuration Update Gatherer",
      "type": "ERDCwindows"
   },
   {
      "description", "Default ping check for win-dleith",
      "elementId": 1,
      "id": 2,
      "isHidden": false,
      "isHostCheck": true,
      "isMonitored": true,
      "name": "PING-win-dleith",
      "type": "Ping"
   }
   {
      "description", "Default ping check for rd-01",
      "elementId": 8,
      "id": 306,
      "isHidden": false,
      "isHostCheck": true,
      "isMonitored": true,
      "name": "PING-rh-01"
      "type": "Ping"
   },
   ...
]



GET /api/v1/monitors/{id}

List a specific service monitor.

Returned Fields

For each returned service monitor the following fields are provided:

FieldTypeDescription
descriptionStringdescription of this service monitor
elementIdIntegerID for this service monitor's parent Element; can return a null value for unassigned monitors
idIntegerID for this Element
isHiddenBooleanhidden monitors are internal monitors that Uptime Infrastructure Monitor uses, and can be ignored
isMonitoredBooleanmonitoring status for this Element
isHostCheckBooleanreturns true if this service monitor is the host check for its parent Element
isHiddenBooleanhidden monitors are internal monitors that Uptime Infrastructure Monitor uses, and can be ignored
nameStringdisplay name of the service monitor
typeString

the service monitor type, typically as seen in the Uptime Infrastructure Monitor UI

Response Codes

The following common response codes may result from this operation:

Other response codes that may occur include the following:

Response Code

Code Description

HTTP Status Code

Details

 OK200Information retrieved successfully.
UT-1001Monitor Does Not Exist404

A specifically referenced service monitor ID does not exist.

In such a case, referencing
https://youruptime:9997/api/v1/monitors/456/
returns the following:

The service monitor id '456' does not exist.

UT-1011Monitor Filter Expired410

The referenced filter is expired. Created filters persist, by default, for five minutes.

UT-1014Invalid Monitor Filter400The referenced Element filter does not exist.

Example

List a specific service monitor (for example, ID #364):

GET https://youruptime/api/v1/monitors/364

{
   "description": "Collects basic performance data",
   "elementId": 1,
   "id": 3,
   "isHidden": true,
   "isHostCheck": false,
   "isMonitored": true,
   "name": "Platform Performance Gatherer",
   "type": "ERDCwindows"
}

 


GET /api/v1/monitors/{id}/status

Produces basic availability information, similar to the status shown on Global Scan. The 'status' task can only be called against one service monitor at a time, based on ID.

Returned Fields

For the returned Element, the following fields are provided:

FieldTypeDescription
elementIdIntegerID for this service monitor's parent Element; can be null for unassigned monitors
elementStatusObjectan object listing the status of the parent Element for this monitor
(see Element Status Object below for more detail)
idIntegerID for this service monitor
isMonitoredBooleanmonitoring Status for this service monitor
isHiddenBooleanhidden monitors are internal monitors that Uptime Infrastructure Monitor uses, and can be ignored
isHostCheckBooleanreturns true if this service monitor is the host check for its parent Element
lastCheckTimeString - Date Timethe last time this service monitor was executed successfully
lastTransitionTimeString - Date Timethe last time this service monitor changed status, which can be used to determine time in its current status
messageStringoutput message produced the last time the service monitor was executed
nameStringname of this service monitor
statusStringlast known status of this service monitor
Element Status Object

If this service monitor has a parent Element, its status details are listed in the elementStatus object:

FieldTypeDescription
idIntegerID of the parent Element
isMonitoredBooleanmonitoring status for the parent Element
nameStringdisplay name of the parent Element
messageStringoutput message produced the last time the parent Element changed status
statusStringlast known status of the parent Element
lastCheckTimeString - Date Timethe last time the parent Element's status was successfully checked  
lastTransitionTimeString - Date Timethe last time the parent Element changed status, which can be used to determine time in its current status
powerStateStringthe current power state of the parent Element (only provided for virtual Elements; all other Elements return null)

Response Codes

The following common response codes may result from this operation:

Other response codes that may occur include the following:

Response Code

Code Description

HTTP Status Code

Details

 OK200Information retrieved successfully.
UT-1001Monitor Does Not Exist404

A specifically referenced service monitor ID does not exist.

In such a case, referencing
https://youruptime:9997/api/v1/monitors/456/
returns the following:

The service monitor id '456' does not exist.

UT-1011Monitor Filter Expired410

The referenced filter is expired. Created filters persist, by default, for five minutes.

UT-1014Invalid Monitor Filter400The referenced Element filter does not exist.

Example

GET https://youruptime/api/v1/monitors/1/status

{
   "elementId": 1,
   "elementStatus": 
   {
         "id": 1,
         "isMonitored": true,
         "lastCheckTime": "2012-09-17T14:14:17",
         "lastTransitionTime": "2012-09-13T11:34:24",
         "message": "",
         "name": "win-dleith",
         "powerState": "On",
         "status": "OK"
   },
   "id": 1,
   "isHidden": false,
   "isHostCheck": false,
   "isMonitored": true,
   "lastCheckTime": "2012-09-17T14:13:56",
   "lastTransitionTime": "2012-09-13T11:34:38",
   "message": "",
   "name": "UPTIME-win-dleith",
   "status": "UNKNOWN"
}