Working with Service Monitors

Summary

/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:

Field	Required	Description
metricType	Yes	The type of metrics to return: 2 = Int; 3 = Decimal; 4 = String.
startDateTime	No	The start time of the period for the desired metrics in the 'ddMMyyyyHHmmss' format.
endDateTime	No	The 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:

Field	Type	Description
metricData	Array	An 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:

Field	Type	Description
dataTime	String - Date Time	The data and time when the metric was collected.
value	Integer, Decimal, or String	The metric value.

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 be 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 Uptime Infrastructure Monitor 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 fulfilling the request. 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 fulfilling the request. 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 fulfilling the request. 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-1000	Element Does Not Exist	404	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-1010	Element Filter Expired	410	The referenced filter is expired. Created filters persist, by default, for five minutes.
UT-1012	Element Group Filter Expired	410	The referenced group filter is expired. Created filters persist, by default, for five minutes.
UT-1013	Invalid Element Filter	400	The JSON used to create an Element filter is invalid, and cannot be parsed. Check to ensure you are posting well-formed JSON.
UT-1015	Invalid Element Group Filter	400	The JSON used to create an Element group filter is invalid, and cannot be parsed. Check to ensure you are posting well-formed JSON.
UT-1028	URL ID Body Mismatch	400	The 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:

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 Uptime Infrastructure Monitor uses, and can 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 Uptime Infrastructure Monitor 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 be 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 Uptime Infrastructure Monitor 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 fulfilling the request. 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 fulfilling the request. 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 fulfilling the request. 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 referenced filter is expired. Created filters persist, by default, for five minutes.
UT-1014	Invalid Monitor Filter	400	The 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:

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 Uptime Infrastructure Monitor uses, and can 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 Uptime Infrastructure Monitor uses, and can be ignored
name	String	display name of the service monitor
type	String	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:

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 be 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 Uptime Infrastructure Monitor 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 fulfilling the request. 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 fulfilling the request. 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 fulfilling the request. 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/`returns the following: `The service monitor id '456' does not exist.`
UT-1011	Monitor Filter Expired	410	The referenced filter is expired. Created filters persist, by default, for five minutes.
UT-1014	Invalid Monitor Filter	400	The 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:

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 Uptime Infrastructure Monitor uses, and can 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 are 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 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 be 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 Uptime Infrastructure Monitor 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 fulfilling the request. 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 fulfilling the request. 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 fulfilling the request. 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/` returns the following: `The service monitor id '456' does not exist.`
UT-1011	Monitor Filter Expired	410	The referenced filter is expired. Created filters persist, by default, for five minutes.
UT-1014	Invalid Monitor Filter	400	The 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"
}

Page tree

Working with Service Monitors

Summary

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

Arguments

Returned Fields

Metric Data Array

Response Codes

Example

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