RPC API Developer's Guide

Get Alerts

Note that LogicMonitor has a REST API equivalent for this API available.

The LogicMonitor API allows users to manage alerts programmatically with the getAlerts call.  With the getAlerts call you can retrieve information about alerts in your LogicMonitor account. Add filter parameters to narrow down the number of alerts returned.  If no input parameters are specified, alert data for all alerts will be returned.  LogicMonitor limits the number of alerts returned by getAlerts in cases where a large number of alerts are being requested. Therefore, if you are retrieving alert data for a large number of alerts, you'll need to use multiple getAlerts requests to get the data (using start and results parameters).

Notes:

  • As with all of our API calls, authentication is required.
  • The getAlerts RPC will only return alerts that a user has permission to view

 

getAlerts

URL:
https://accountName.logicmonitor.com/santaba/rpc/getAlerts?c=accountName&u=user&p=password&id=alertId&type=alertType&group=hostgroupName&host=hostName&hostId=hostId&dataSource=dataSourceName&dataPoint=dataPointName&startEpoch=startTime&endEpoch=endTime&ackFilter=all&filterSDT=false&level=alertLevel&orderBy=orderBy&orderDirection=asc&includeInactive=false&needTotal=false&results=numberOfResults&start=startResult&needMessage=false
 

Request Parameters: You can include the following as query parameters in a getAlerts request:

Parameter

Type

Description

id Integer Optional. The id of the alert to return, where the alert type must also be specified.
type String Required if id is specified. alert | eventalert | batchjobalert
The type of alerts to return.
group String Optional. The name of the host group that you want to retrieve alert data for. This value is interchangeable with the hostGroupId.
host String Optional. The name of the host that you want to retrieve alert data for. This value is interchangeable with the hostId.
hostId Integer Optional. The Id of the host that you want to retrieve alert data for. This value is interchangeable with the host value.
dataSource String Optional. The display name of the dataSource that you want to retrieve alert data for.

Note: if you are trying to get all alerts for the instances of a multi-instance datasource, you need to include * at the end of the datasource name. For example, consider the multi-instance datasource Host Uptime-, you need to specify Host Uptime-* to get all alerts for all instances of Host Uptime.

dataPoint String Optional. The name of the dataPoint that you want to retrieve alert data for.
timing string Optional. start | overlap, defaults to overlap. If timing=start, only alerts that started between startEpoch and endEpoch will be returned. If timing=overlap, any alert that was active during startEpoch and endEpoch will be returned. Note that it is not necessary to specify both startEpoch and endEpoch.
startEpoch Long Optional. If timing=start, only alerts that started after this value will be returned. If timing=overlap, any alert that was active for the startEpoch will be returned. Note that it is not necessary to specify both startEpoch and endEpoch.
endEpoch Long Optional. If specified, only alerts that started before this value will be returned. Note that it is not necessary to specify both startEpoch and endEpoch.
ackFilter String Optional. all (default) | acked | nonacked
Only alerts that match this filter value will be returned.

all: Both non-acknowledged alerts and acknowledged alerts will be returned.

acked: Alerts that have been acknowledged will be returned.

nonacked: Alerts that have not been acknowledged will be returned.

filterSDT String Optional. true | false | sdt
This value indicates whether or not alerts that are associated with hosts or datasources that are experiencing an SDT should be returned.

true: Alerts associated with hosts or datasources that are experiencing an SDT will not be returned.

false: Alerts associated with hosts or datasources that are experiencing an SDT will be included in the returned alerts.

sdt: Alerts associated with hosts or datasources that are experiencing an SDT will be returned.

level String Optional. all | warn | error | critical
The minimum level of alerts to return alert data for.
orderBy String Optional. host | dataSource | dataPoint | level | ackedOn | startOn | endOn
This value indicates how returned alert data should be ordered.
orderDirection String Optional. asc | desc
This value indicates the order direction for returned alert data that is ordered (i.e. by specifying orderBy). Acceptable values include asc and desc for ascending order and descending order, respectively.
includeInactive String Optional. true | false (default)

true: Both active and cleared alert records will be returned (i.e. both active and inactive alert details).

false: Only active alert details will be returned.

Note:the results parameters is required if you set includeInactive=true

results Integer Required if the includeInactive=true is included in the request. The number of alerts that should be returned. 
start Integer Optional. This value indicates what number alert result to start displaying on (e.g. start=21 starts returning alerts from the 21st alert).
needMessage Boolean Optional. true | false (default)
When this value is set to true, returned alert data will include alert message bodies.

 

All outputs will be in the format: { [status], [data], [errmsg] }, where status is the status of the response, errmsg is the error message associated with the response, and the data object includes the following:

Value

Description

total The total number of alerts that satisfy the criteria specified in the call. A negative number indicates that we didn't return all alerts that satisfy the request criteria, and that "at least" that number of alerts exist. For example, if you request the first 500 alerts and you have 3000 alerts in your account, the response may include total=-1000 (i.e. you have at least 1000 alerts, but you didn't ask for them all).
alerts A JSON object that contains an object for each alert that satisfies the criteria specified in the request. The following properties/objects will be displayed for each alert object:
  • nextRecipient
  • dataSourceInstance
  • alertRuleName
  • dataSource
  • endOn
  • hostId
  • type
  • dataSourceId
  • ackedOnLocal
  • id
  • thresholds
  • level
  • endOnLocal
  • ackComment
  • value
  • alertEscalationChainName
  • hostGroups (this object contains one object per group, where the following properties will be displayed for each group: alertEnable, createdOn, groupType, id, parentId, description, appliesTo, name, fullPath.)
  • startOnLocal
  • dataPoint
  • ackedBy
  • host
  • dataSourceInstanceId
  • ackedOn
  • escalationChainId
  • escalationSubChainId
  • alertRecipients
  • startOn
  • duration
  • dataSourceInstanceDescription
  • active
  • hostDataSourceId
  • acked
  • displayname

 

Example

Request:
curl "https://apiAccount.logicmonitor.com/santaba/rpc/getAlerts?c=apiAccount&u=apiUser&p=password&ackFilter=nonacked&level=warn&dataPoint=idleInterval"
  Response:
{
  "status": 200,
  "data": {
    "total": 2,
    "alerts": [
      {
        "nextRecipient": 12,
        "dataSourceInstance": "HostStatus",
        "alertRuleName": "Dev-QA Warn",
        "dataSource": "HostStatus",
        "endOn": 0,
        "hostId": 196,
        "type": "alert",
        "dataSourceId": 119,
        "ackedOnLocal": "",
        "id": 3871,
        "thresholds": "> 300 300 300",
        "level": "critical",
        "endOnLocal": "",
        "ackComment": "",
        "value": "601011.43",
        "alertEscalationChainName": "Warn",
        "hostGroups": [{
          "alertEnable": true,
          "createdOn": 1424128277,
          "groupType": 0,
          "id": 6,
          "parentId": 1,
          "description": "",
          "appliesTo": "",
          "name": "Dev-QA",
          "fullPath": "Dev-QA"
        }],
        "startOnLocal": "2015-11-09 11:25:39 PST",
        "dataPoint": "idleInterval",
        "ackedBy": "",
        "host": "10.0.1.35",
        "dataSourceInstanceId": 2008,
        "ackedOn": 0,
        "escalationChainId": 14,
        "escalationSubChainId": 0,
        "alertRecipients": "{\"hipchat_warn\":[\"admin\"]}",
        "startOn": 1447097139,
        "duration": "166h 52m",
        "dataSourceInstanceDescription": "",
        "active": true,
        "hostDataSourceId": 4850,
        "acked": false,
        "displayName": "Host Status"
      },
      {
        "nextRecipient": 45,
        "dataSourceInstance": "HostStatus",
        "alertRuleName": "Dev-QA Warn",
        "dataSource": "HostStatus",
        "endOn": 0,
        "hostId": 201,
        "type": "alert",
        "dataSourceId": 119,
        "ackedOnLocal": "",
        "id": 3230,
        "thresholds": "> 300 300 300",
        "level": "critical",
        "endOnLocal": "",
        "ackComment": "",
        "value": "2820495.43",
        "alertEscalationChainName": "Warn",
        "hostGroups": [{
          "alertEnable": true,
          "createdOn": 1424128277,
          "groupType": 0,
          "id": 6,
          "parentId": 1,
          "description": "",
          "appliesTo": "",
          "name": "Dev-QA",
          "fullPath": "Dev-QA"
        }],
        "startOnLocal": "2015-10-14 19:54:53 PDT",
        "dataPoint": "idleInterval",
        "ackedBy": "",
        "host": "172.16.19.128",
        "dataSourceInstanceId": 2162,
        "ackedOn": 0,
        "escalationChainId": 14,
        "escalationSubChainId": 0,
        "alertRecipients": "{\"hipchat_warn\":[\"admin\"]}",
        "startOn": 1444877693,
        "duration": "783h 23m",
        "dataSourceInstanceDescription": "",
        "active": true,
        "hostDataSourceId": 5083,
        "acked": false,
        "displayName": "Host Status"
      }
    ]
  },
  "errmsg": "OK"
}

 

More getAlerts examples

The following example returns the 1st to 100th alerts (0-based) in apiAccount by specifying start and results:

curl "https://apiAccount.logicmonitor.com/santaba/rpc/getAlerts?c=apiAccount&u=apiUser&p=example&start=1&results=100"

 

The following example returns alerts 100-200 in apiAccount by specifying start and results:

curl "https://apiAccount.logicmonitor.com/santaba/rpc/getAlerts?c=apiAccount&u=apiUser&p=example&start=100&results=100"

 

The following example returns all alerts for the host group "webservers":

curl "https://apiAccount.logicmonitor.com/santaba/rpc/getAlerts?c=apiAccount&u=apiUser&p=example&group=webservers"

 

The following example returns all non-acknowledged alerts for the host group "webservers":

curl "https://apiAccount.logicmonitor.com/santaba/rpc/getAlerts?c=apiAccount&u=apiUser&p=example&group=webservers&ackFilter=nonacked"

 

The following example returns all alerts for the datasource "WinLogicDisk" of the host "Server1", where returned alerts are sorted by the alert starting time in descending order:

curl "https://apiAccount.logicmonitor.com/santaba/rpc/getAlerts?c=apiAccount&u=apiUser&p=example&host=Server1&dataSource=WinLogicDisk&orderBy=startOn&orderDirection=desc"