Summary
Section | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Anchor | ||||
---|---|---|---|---|
|
List all Element groups visible to the user account, as well as each Element groups' member Elements and monitors.
Returned Fields
For each returned Element group, the following fields are provided:
Field | Type | Description |
---|---|---|
description | String | description of this Element group |
elements | Array | an array listing the Elements that belong to this Element group (see Elements Array below for details) |
groupId | Integer | ID for this Element group's parent group; can return a null value for the top-level group |
id | Integer | ID for this Element group |
monitors | Array | an array listing the service monitors that belong to the Elements in this Element group (see Monitors Array below for details) |
name | String | the name of this Element group |
Elements Array
The following fields are provided for each Element belonging directly to an Element group:
Field | Type | Description |
---|---|---|
id | Integer | ID for the child Element |
isMonitored | Boolean | monitoring status for the child Element |
name | String | display name for the child Element |
Monitors Array
The following fields are provided for each service monitor belonging to Elements that belong to this Element group:
Field | Type | Description |
---|---|---|
elementId | Integer | ID of the Element this child service monitor is related to; can be null for unassigned monitors |
id | Integer | ID for the child service monitor |
isHidden | Boolean | hidden monitors are internal monitors that up.time uses, and can generally be ignored |
isMonitored | Boolean | monitoring status for the child service monitor |
name | String | name of the child service monitor |
Response Codes
The following common response codes may result from this operation:
Include Page | ||||
---|---|---|---|---|
|
Other response codes that may occur include the following:
Response Code | Code Description | HTTP Status Code | Details |
---|---|---|---|
OK | 200 | Information retrieved successfully. | |
UT-1012 | Element Group Filter Expired | 410 | The filter you are referencing has expired. Created filters persist, by default, for 5 minutes. |
UT-1015 | Invalid Element Group Filter | 400 | The Element filter you are referencing does not exist. |
Example
List all Element groups visible to the user:
GET https://youruptime/api/v1/groups/
Code Block |
---|
[ { "description": "Collects basic performance data", "elements": [ { "id": 1, "isMonitored": true, "name": "win-dleith" }, { "id": 2, "isMonitored": true, "name": "rd-vc2" } ], "groupId": null, "id": 1, "monitors": [ { "elementId": 1, "id": 2, "isHidden": false, "isMonitored": true, "name": "PING-localhost" }, ... ], "name": "My Infrastructure", }, { "description": "", "elements": [ ... ], "groupId": 1, "id": 2, "monitors": [ ... ], "name": "Discovered Virtual Machines", }, { "description": "", "elements": [ ... ], "groupId": 1, "id": 3, "monitors": [ ... ], "name": "Discovered Hosts", }, ... ] |
Anchor | ||||
---|---|---|---|---|
|
List a specific Element group's member Elements and monitors.
Returned Fields
The following fields are provided:
Field | Type | Description |
---|---|---|
description | String | description of this Element group |
elements | Array | an array listing the Elements that belong to this Element group (see Elements Array below for details) |
groupId | Integer | ID for this Element group's parent group; can return a null value for the top-level group |
id | Integer | ID for this Element group |
monitors | Array | an array listing the service monitors that belong to the Elements in this Element group (see Monitors Array below for details) |
name | String | the name of this Element group |
Elements Array
The following fields are provided for each Element belonging directly to an Element group:
Field | Type | Description |
---|---|---|
id | Integer | ID for the child Element |
isMonitored | Boolean | monitoring status for the child Element |
name | String | display name for the child Element |
Monitors Array
The following fields are provided for each service monitor belonging to Elements that belong to this Element group:
Field | Type | Description |
---|---|---|
elementId | Integer | ID of the Element this child service monitor is related to; can be null for unassigned monitors |
id | Integer | ID for the child service monitor |
isHidden | Boolean | hidden monitors are internal monitors that up.time uses, and can generally be ignored |
isMonitored | Boolean | monitoring status for the child service monitor |
name | String | name of the child service monitor |
Response Codes
The following common response codes may result from this operation:
Include Page | ||||
---|---|---|---|---|
|
Other response codes that may occur include the following:
Response Code | Code Description | HTTP Status Code | Details |
---|---|---|---|
OK | 200 | Information retrieved successfully. | |
UT-1002 | Element Group Does Not Exist | 404 | A specifically referenced Element group does not exist. In such a case, referencing
|
UT-1012 | Element Group Filter Expired | 410 | The filter you are referencing has expired. Created filters persist, by default, for 5 minutes. |
UT-1015 | Invalid Element Group Filter | 400 | The Element filter you are referencing does not exist. |
UT-1044 | Field Number out of Range | n/a | The declared Element group ID needs to be equal to or greater than 1. |
Example
List the contents of Element group ID 1:
GET https://youruptime/api/v1/groups/1
Code Block |
---|
[ { "description": "Collects basic performance data", "elements": [ { "id": 1, "isMonitored": true, "name": "win-dleith" }, { "id": 2, "isMonitored": true, "name": "rd-vc2" } ], "groupId": null, "id": 1, "monitors": [ { "elementId": 1, "id": 2, "isHidden": false, "isMonitored": true, "name": "PING-localhost" }, ... ], "name": "My Infrastructure", }, { "description": "", "elements": [ ... ], "groupId": 1, "id": 2, "monitors": [ ... ], "name": "Discovered Virtual Machines", }, { "description": "", "elements": [ ... ], "groupId": 1, "id": 3, "monitors": [ ... ], "name": "Discovered Hosts", }, ... ] |
Anchor | ||||
---|---|---|---|---|
|
Display the status of an Element group's member Elements and monitors.
Returned Fields
The following fields are provided for the returned Element group:
Field | Type | Description |
---|---|---|
elementStatus | Array | an object listing the status of the parent Element for this monitor (see Element Status Array below for details) |
id | Integer | ID for this service monitor |
monitorStatus | Array | the output message produced the last time the service monitor was executed (see Monitor Status Array below for details) |
name | String | name of this service monitor |
topologyParentStatus | Array | last known status of this service monitor (see Topology Status Array below for details) |
Element Status Array
The following fields are provided for each Element in the Element group:
Field | Type | Description |
---|---|---|
id | Integer | ID of the child Element |
isMonitored | Boolean | monitoring status for the child Element |
name | String | display name of the child Element |
message | String | the output message produced the last time the child Element changed status |
status | String | last known status of the child Element |
lastCheckTime | String - Date Time | the last time the child Element's status was successfully checked |
lastTransitionTime | String - Date Time | last time the child Element changed status, which can be used to determine time in its current status |
powerState | String | the current power state of the child Element (only provided for virtual Elements; all other Elements will return null) |
Monitor Status Array
The following fields are provided for each service monitor associated with Elements in the Element group:
Field | Type | Description |
---|---|---|
elementId | Integer | ID of the Element this monitor is related to |
id | Integer | ID of the 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 |
isMonitored | Boolean | monitoring status for the service monitor |
name | String | name of the service monitor |
message | String | output message produced the last time the service monitor was executed |
status | String | last known status of this service monitor |
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 at its current status |
Topology Status Array
The topologyParentStatus
array can be used to map topological dependency failures using identified parent child Element relationships:
Field | Type | Description |
---|---|---|
id | Integer | ID for this service monitor |
isMonitored | Boolean | monitoring status for the parent Element |
lastCheckTime | String - Date Time | the last time the parent Element was checked successfully |
lastTransitionTime | String - Date Time | the last time this parent Element changed status, which can be used to determine time at its current status |
message | String | output message produced the last time the parent's status changed |
name | String | display name of the parent Element |
powerState | String | the current power state of the parent Element (only provided for virtual Elements; all other Elements will return null) |
status | String | last known status of the parent Element |
Response Codes
The following common response codes may result from this operation:
Include Page | ||||
---|---|---|---|---|
|
Other response codes that may occur include the following:
Response Code | Code Description | HTTP Status Code | Details |
---|---|---|---|
OK | 200 | Information retrieved successfully. | |
UT-1002 | Element Group Does Not Exist | 404 | A specifically referenced Element group does not exist. In such a case, referencing
|
UT-1012 | Element Group Filter Expired | 410 | The filter you are referencing has expired. Created filters persist, by default, for 5 minutes. |
UT-1015 | Invalid Element Group Filter | 400 | The Element filter you are referencing does not exist. |
UT-1044 | Field Number out of Range | n/a | The declared Element group ID needs to be equal to or greater than 1. |
Example
Retrieve status for Element group ID 1 (by default, the My Infrastructure group):
GET https://youruptime/api/v1/groups/1/status
Code Block |
---|
{ "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, "monitorStatus": [ { "elementId": 1, "id": 7, "isHidden": false, "isHostCheck": false, "isMonitored": true, "lastCheckTime": "2012-09-17T14:13:56", "lastTransitionTime": "2012-09-17T14:05:56", "message": "", "name": "Default File System Capacity", "status": "UNKNOWN" }, ... ] "name": "My Infrastructure", "topologyParentStatus": [ { "id": 2, "isMonitored": true, "lastCheckTime": "2012-09-17T14:14:17", "lastTransitionTime": "2012-09-13T11:34:24", "message": "", "name": "rd-vc2", "powerState": null, "status": "OK" }, ... ] } |