Summary

 

GET
GET
GET

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


GET /api/v1/monitors

List service monitors visible to the authenticated user account.

Returned Fields

For each returned service monitor the following fields will be 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 up.time uses, and can generally 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 up.time 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 Expired410The filter you are referencing has expired. Created filters persist, by default, for 5 minutes.
UT-1014Invalid Monitor Filter400The Element filter you are referencing 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": "up.time 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 will be 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 up.time uses, and can generally 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 up.time uses, and can generally be ignored
nameStringdisplay name of the service monitor
typeString

the service monitor type, typically as seen in the up.time 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/ would return the following:

The service monitor id '456' does not exist.

UT-1011Monitor Filter Expired410The filter you are referencing has expired. Created filters persist, by default, for 5 minutes.
UT-1014Invalid Monitor Filter400The Element filter you are referencing 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 will be 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 up.time uses, and can generally 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 will be 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 will 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/ would return the following:

The service monitor id '456' does not exist.

UT-1011Monitor Filter Expired410The filter you are referencing has expired. Created filters persist, by default, for 5 minutes.
UT-1014Invalid Monitor Filter400The Element filter you are referencing 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"
}