Working with Service Monitors

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:

Field	Type	Description
description	String	description of this service monitor
elementId	Integer	ID for this service monitor's parent Element; can return a null value for unassigned monitors
id	Integer	ID for this Element
isHidden	Boolean	hidden monitors are internal monitors that up.time uses, and can generally be ignored
isMonitored	Boolean	monitoring status for this Element
isHostCheck	Boolean	returns `true` if this service monitor is the host check for its parent Element
name	String	display name of the service monitor
type	String	the service monitor type, typically as seen in the up.time UI

Response Codes

The following common response codes may result from this operation:

Response Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	The request could not be processed by the server due to incorrect syntax. API commands can be accessed with this format: `https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>` If you encounter this error, ensure the referencing URL is correct.
UT-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may have been omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	The user does not have permission to perform the requested action. The user's up.time permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).
UT-0500	Unknown	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented the request from being fulfilled. View the `uptime_controller.log` file for possible issues.
UT-0555	Unknown Exception	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented the request from being fulfilled. In this case, an exception has occurred; as a starting point, look for this exception in the `uptime_controller.log` file.
UT-0560	Internal Server Error	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented the request from being fulfilled. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the `uptime_controller.log` file.

Other response codes that may occur include the following:

Response Code	Code Description	HTTP Status Code	Details
	OK	200	Information retrieved successfully.
UT-1011	Monitor Filter Expired	410	The filter you are referencing has expired. Created filters persist, by default, for 5 minutes.
UT-1014	Invalid Monitor Filter	400	The 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:

Field	Type	Description
description	String	description of this service monitor
elementId	Integer	ID for this service monitor's parent Element; can return a null value for unassigned monitors
id	Integer	ID for this Element
isHidden	Boolean	hidden monitors are internal monitors that up.time uses, and can generally be ignored
isMonitored	Boolean	monitoring status for this Element
isHostCheck	Boolean	returns `true` if this service monitor is the host check for its parent Element
isHidden	Boolean	hidden monitors are internal monitors that up.time uses, and can generally be ignored
name	String	display name of the service monitor
type	String	the service monitor type, typically as seen in the up.time UI

Response Codes

The following common response codes may result from this operation:

Response Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	The request could not be processed by the server due to incorrect syntax. API commands can be accessed with this format: `https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>` If you encounter this error, ensure the referencing URL is correct.
UT-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may have been omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	The user does not have permission to perform the requested action. The user's up.time permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).
UT-0500	Unknown	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented the request from being fulfilled. View the `uptime_controller.log` file for possible issues.
UT-0555	Unknown Exception	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented the request from being fulfilled. In this case, an exception has occurred; as a starting point, look for this exception in the `uptime_controller.log` file.
UT-0560	Internal Server Error	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented the request from being fulfilled. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the `uptime_controller.log` file.

Other response codes that may occur include the following:

Response Code	Code Description	HTTP Status Code	Details
	OK	200	Information retrieved successfully.
UT-1001	Monitor Does Not Exist	404	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-1011	Monitor Filter Expired	410	The filter you are referencing has expired. Created filters persist, by default, for 5 minutes.
UT-1014	Invalid Monitor Filter	400	The 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:

Field	Type	Description
elementId	Integer	ID for this service monitor's parent Element; can be null for unassigned monitors
elementStatus	Object	an object listing the status of the parent Element for this monitor (see Element Status Object below for more detail)
id	Integer	ID for this service monitor
isMonitored	Boolean	monitoring Status for this service monitor
isHidden	Boolean	hidden monitors are internal monitors that up.time uses, and can generally be ignored
isHostCheck	Boolean	returns `true` if this service monitor is the host check for its parent Element
lastCheckTime	String - Date Time	the last time this service monitor was executed successfully
lastTransitionTime	String - Date Time	the last time this service monitor changed status, which can be used to determine time in its current status
message	String	output message produced the last time the service monitor was executed
name	String	name of this service monitor
status	String	last 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:

Field	Type	Description
id	Integer	ID of the parent Element
isMonitored	Boolean	monitoring status for the parent Element
name	String	display name of the parent Element
message	String	output message produced the last time the parent Element changed status
status	String	last known status of the parent Element
lastCheckTime	String - Date Time	the last time the parent Element's status was successfully checked
lastTransitionTime	String - Date Time	the last time the parent Element changed status, which can be used to determine time in its current status
powerState	String	the 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:

Response Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	The request could not be processed by the server due to incorrect syntax. API commands can be accessed with this format: `https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>` If you encounter this error, ensure the referencing URL is correct.
UT-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may have been omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	The user does not have permission to perform the requested action. The user's up.time permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).
UT-0500	Unknown	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented the request from being fulfilled. View the `uptime_controller.log` file for possible issues.
UT-0555	Unknown Exception	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented the request from being fulfilled. In this case, an exception has occurred; as a starting point, look for this exception in the `uptime_controller.log` file.
UT-0560	Internal Server Error	500	The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented the request from being fulfilled. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the `uptime_controller.log` file.

Other response codes that may occur include the following:

Response Code	Code Description	HTTP Status Code	Details
	OK	200	Information retrieved successfully.
UT-1001	Monitor Does Not Exist	404	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-1011	Monitor Filter Expired	410	The filter you are referencing has expired. Created filters persist, by default, for 5 minutes.
UT-1014	Invalid Monitor Filter	400	The 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"
}

Child pages

Working with Service Monitors

Summary

GET /api/v1/monitors

Returned Fields

Response Codes

Example

GET /api/v1/monitors/{id}

Returned Fields

Response Codes

Example

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

Returned Fields

Element Status Object

Response Codes

Example