Summary

 

GET
GET
GET

/api/v1/groups
/api/v1/groups/{id}
/api/v1/groups/{id}/status


GET /api/v1/groups

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:

FieldTypeDescription
descriptionStringdescription of this Element group
elementsArrayan array listing the Elements that belong to this Element group (see Elements Array below for details)
groupIdIntegerID for this Element group's parent group; can return a null value for the top-level group
idIntegerID for this Element group
monitorsArrayan array listing the service monitors that belong to the Elements in this Element group (see Monitors Array below for details)
nameStringthe name of this Element group
Elements Array

The following fields are provided for each Element belonging directly to an Element group:

FieldTypeDescription
idIntegerID for the child Element
isMonitoredBooleanmonitoring status for the child Element
nameStringdisplay 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:

FieldTypeDescription
elementIdIntegerID of the Element this child service monitor is related to; can be null for unassigned monitors
idIntegerID for the child service monitor
isHiddenBooleanhidden monitors are internal monitors that up.time uses, and can generally be ignored
isMonitoredBooleanmonitoring status for the child service monitor
nameStringname of the child service monitor

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-1012Element Group Filter Expired410The filter you are referencing has expired. Created filters persist, by default, for 5 minutes.
UT-1015Invalid Element Group Filter400The Element filter you are referencing does not exist.

Example

List all Element groups visible to the user:

GET https://youruptime/api/v1/groups/

[
   {
      "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",
   },
   ...
]

GET /api/v1/groups/{id}

List a specific Element group's member Elements and monitors.

Returned Fields

The following fields are provided:

FieldTypeDescription
descriptionStringdescription of this Element group
elementsArrayan array listing the Elements that belong to this Element group (see Elements Array below for details)
groupIdIntegerID for this Element group's parent group; can return a null value for the top-level group
idIntegerID for this Element group
monitorsArrayan array listing the service monitors that belong to the Elements in this Element group (see Monitors Array below for details)
nameStringthe name of this Element group
Elements Array

The following fields are provided for each Element belonging directly to an Element group:

FieldTypeDescription
idIntegerID for the child Element
isMonitoredBooleanmonitoring status for the child Element
nameStringdisplay 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:

FieldTypeDescription
elementIdIntegerID of the Element this child service monitor is related to; can be null for unassigned monitors
idIntegerID for the child service monitor
isHiddenBooleanhidden monitors are internal monitors that up.time uses, and can generally be ignored
isMonitoredBooleanmonitoring status for the child service monitor
nameStringname of the child service monitor

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-1002Element Group Does Not Exist404

A specifically referenced Element group does not exist.

In such a case, referencing https://youruptime:9997/api/v1/groups/789/ would return the following:

The element group id '789' does not exist.

UT-1012Element Group Filter Expired410The filter you are referencing has expired. Created filters persist, by default, for 5 minutes.
UT-1015Invalid Element Group Filter400The Element filter you are referencing does not exist.
UT-1044Field Number out of Range

n/a
(JSON validation)

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

[
   {
      "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",
   },
   ...
]

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

Display the status of an Element group's member Elements and monitors.

Returned Fields

The following fields are provided for the returned Element group:

FieldTypeDescription
elementStatusArrayan object listing the status of the parent Element for this monitor (see Element Status Array below for details)
idIntegerID for this service monitor
monitorStatusArraythe output message produced the last time the service monitor was executed (see Monitor Status Array below for details)
nameStringname of this service monitor
topologyParentStatusArraylast 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:

FieldTypeDescription
idIntegerID of the child Element
isMonitoredBooleanmonitoring status for the child Element
nameStringdisplay name of the child Element
messageStringthe output message produced the last time the child Element changed status
statusStringlast known status of the child Element
lastCheckTimeString - Date Timethe last time the child Element's status was successfully checked 
lastTransitionTimeString - Date Timelast time the child Element changed status, which can be used to determine time in its current status
powerStateStringthe 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
elementIdIntegerID of the Element this monitor is related to
idIntegerID of the 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
isMonitoredBooleanmonitoring status for the service monitor
nameStringname of the service monitor
messageStringoutput message produced the last time the service monitor was executed
statusStringlast known status of this service monitor
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 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
idIntegerID for this service monitor
isMonitoredBooleanmonitoring status for the parent Element
lastCheckTimeString - Date Timethe last time the parent Element was checked successfully
lastTransitionTimeString - Date Timethe last time this parent Element changed status, which can be used to determine time at its current status
messageStringoutput message produced the last time the parent's status changed
nameStringdisplay name of the parent Element
powerStateStringthe current power state of the parent Element (only provided for virtual Elements; all other Elements will return null)
statusStringlast known status of the parent Element

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-1002Element Group Does Not Exist404

A specifically referenced Element group does not exist.

In such a case, referencing https://youruptime:9997/api/v1/groups/789/ would return the following:

The element group id '789' does not exist.

UT-1012Element Group Filter Expired410The filter you are referencing has expired. Created filters persist, by default, for 5 minutes.
UT-1015Invalid Element Group Filter400The Element filter you are referencing does not exist.
UT-1044Field Number out of Range

n/a
(JSON validation)

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

{
   "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"
      },
      ...
   ]
}