Alerts API

This article provides sample API calls used for obtaining and creating Alerts.

PREREQUISITES:

Get all Alerts for a specific Metric

Get all Alerts for a specific Metric

You can fetch the list of all alerts for a specific Metric. NOTE: You might get empty result.

  1. Item: metric_alert
  2. Method: GET
  3. element: Specify the element ID in this field. Element ID can be determined in the web browser URL of its editor. For example:
https://demo.metricinsights.com/chart/index/index/element/284

4.     Run Request

Get only recent Alerts (or Alerts for a specific time period)

Get only recent Alerts (or Alerts for a specific time period)

or qualify each metric by time range

  1. Item: alert_rule
  2. Method: POST
  3. element: Specify the element ID in this field. Element ID can be determined in the web browser URL of its editor. For example:
https://demo.metricinsights.com/chart/index/index/element/284
  1. start_time/end_time: Define a date range for which the alerts should be shown.
  2. Run Request

Create an Alert Rule (multiple types)

Parameter Type Description Possible Values
name string A unique name of the alert, defined by a user. user_defined_name
element integer Specify the unique identification number assigned to the element for which the alert is created. You can find element ID in the link of the element Editor/Viewer. element_id
report integer A unique number assigned to the report for which the alert is created. You can find report ID in the link of the report Editor/Viewer. report_id
type enum Define the type of condition that causes creation of an alert in the system. alert_type = 'fixed
value', 'prior value', 'average', 'target', 'volatility
band', 'compound', 'stoplight', 'unusual value', 'best ever', 'worst ever'
alert_rule enum There are two types of alerts in Metric Insights: KPI and global alerts. Specify the "user" value in order to create a KPI alert and global for the second type. alert_rule_type = 'user', 'global'
alert_visibility enum The alert can be available ether to all users who have access to this metric public or to you only private. 'public', 'private'
assign_type enum Define the entity to which the given alert is assigned. 'element', 'segment_value', 'category', 'favorite'
send_alert_to_phone enum Define whether the alert shall be sent as a notification on a mobile device. 'Y', 'N'
comparison_type enum Specify the type of condition that causes the alert triggering. 'fixed', 'pct variance', 'less fixed', 'less pct variance'
comparison_interval_compare_to_period varchar Specify the period to which the comparison should be made. 'day', 'week', 'month', 'quarter', 'year'
comparison_interval_period varchar Define the period for which values should be compared. 'day', 'week', 'month', 'quarter', 'year'
comparison_interval integer Define how many comparison periods should be taken into consideration. DEFAULT NULL
percentage_comparison_type enum For more details refer to this article 'above', 'above
or equal', 'below', 'below or equal', 'above or below', 'within', 'between', 'equal'
comparison_fixed_value Designate the fixed value to which the conditions triggering the alert creation should be applied. DEFAULT NULL
comparison_fixed_value_upper_bound Define the upper bound value in the range of appropriate values. DEFAULT NULL
comparison_percentage_tolerance integer Define the percantage below or above which the alarm notification shall be created. DEFAULT NULL
range_of_values_scope enum Designate the value condition in accordance to which the alert should be created. 'above', 'below', 'above
or below'
compare_line integer Specfy the unique identification number of a compare line. DEFAULT NULL
immediate_notification_ind enum Define whether notification shall be sent: 'Y' - immediately, 'N' - as an email digest, 'None - shown in browser only. 'Y', 'N', 'None'
send_notification_via enum Specify the means of sending the notification in this parameter. 'email', 'sms'
trigger_alert_when enum Specify when the alert is supposed to be sent. 'first time only', 'every time', 'frequently'
trigger_alert_when_frequently enum Define additional conditions if you the 'frequently' value has been chosen for the trigger_alert_when parameter. 'first time only', 'every time', 'frequently'
frequently_condition_values / frequently_condition_satisfied integer Designate how many times the condition should be met and how many times it should be satisfied to trigger the alert. NOT NULL

Target Alert Rule Type

Target Alert Rule Type
  1. Item: alert_rule
  2. Method: POST
  3. ID: Find an existing Alert of the Target type that you wish to use as a foundation for new Alert; open its Editor and find its ID in the web browser URL. For example:
 https://demo.metricinsights.com/editor/kpialertrule/edit/id/1442
  1. Modify any parameters of this request according to your requirements
  2. Run Request

Fixed Value Rule Type

Fixed Value Rule Type
  1. Item: alert_rule
  2. Method: POST
  3. ID: Find an existing Alert of a Fixed Value type that you wish to use as a foundation for new Alert; open its Editor and find its ID in the web browser URL. For example:
 https://demo.metricinsights.com/editor/kpialertrule/edit/id/1444
  1. Modify any parameters of this request according to your requirements
  2. Run Request

Prior Value Rule Type

Prior Value Rule Type
  1. Item: alert_rule
  2. Method: POST
  3. ID: Find an existing Alert with a Prior Value type that you wish to use as a foundation for new Alert; open its Editor and find its ID in the web browser URL. For example:
 https://demo.metricinsights.com/editor/kpialertrule/edit/id/1449
  1. Modify any parameters of this request according to your requirements
  2. Run Request

Recent Volatility Rule Type

Recent Volatility Rule Type
  1. Item: alert_rule
  2. Method: POST
  3. ID: Find an existing Alert with a Volatility Levels type that you wish to use as a foundation for new Alert; open its Editor and find its ID in the web browser URL. For example:
 https://demo.metricinsights.com/editor/kpialertrule/edit/id/2891
  1. Modify any parameters of this request according to your requirements
  2. Run Request

Combination of Multiple Alerts Rule Types

Combination of Multiple Alerts Rule Types
  1. Item: alert_rule
  2. Method: POST
  3. ID: Find an existing Alert with a Compound type that you wish to use as a foundation for the new Alert; open its Editor and find its ID in the web browser URL. For example:
 https://demo.metricinsights.com/editor/kpialertrule/edit/id/2891
  1. Modify any parameters of this request according to your requirements
  2. Run Request

Global Alert Rule Type

Global Alert Rule Type
  1. Item: alert_rule
  2. Method: POST
  3. ID: Find an existing Global Alert Rule that you wish to use as a foundation for the new Alert; open its Editor and find its ID in the web browser URL. For example:
 https://demo.metricinsights.com/editor/alertrule/edit/id/1456
  1. Modify any parameters of this request according to your requirements
  2. Run Request

User Alert Subscriptions

You can use API toolkit to easily manage users' Alert subscriptions.

View all User Subscriptions to Alerts

View all User Subscriptions to Alerts

You can review all the Alerts certain user is subscribed to.

  1. Item: alert_user_share
  2. Method: GET
  3. User: Specify user ID. To determine the ID of a specific user, open the User Editor and find ID in the web browser URL. For example:
 https://demo.metricinsights.com/admin/user/edit/id/1

4.    Request URL (generated automatically): 

https://demo.metricinsights.com/api/alert_rule_user_share?user=1

5.     Run Request

NOTE:

Dimension value "-1" stands for all dimension values.

Create User Subscription to an Alert Rule

Create User Subscription to an Alert Rule

You can subscribe users to specific Alert Rules (one user to one Alert rule at a time).

  1. Item: alert_rule_user_share
  2. Method: POST
  3. ID: Enter the ID of previously created "alert_rule+user" combination. To see the list of all such pairs, choose GET method, leave ID, alert_rule and user fields empty and Run Request. All "alert_rule+user" combinations are going to be displayed in the Raw response field. Choose the one that is supposed to serve as a foundation for the new combination.
  4. alert_rule: Specify the alert rule ID. To determine the ID of a specific Alert, open the Alert Editor and find ID in the web browser URL. For example:
https://demo.metricinsights.com/editor/kpialertrule/edit/id/9

5.     User: Specify user ID. To determine the ID of a specific user, open the User Editor and find ID in the web browser URL. For example:

 https://demo.metricinsights.com/admin/user/edit/id/1

6.     Run Request

Unsubscribe a User from the Alert Rule

Unsubscribe a User from the Alert Rule

This procedure allows deleting certain alert rule subscriptions.

  1. Item: alert_rule_user_share
  2. Method: DELETE
  3. ID: Enter the ID of the "alert_rule+user" combination to be deleted. To see the list of all such pairs, choose GET method, leave ID, alert_rule and user fields empty and Run Request. All "alert_rule+user" combinations are going to be displayed in the Raw response field. Choose the one which is supposed to be deleted.
  4. Run Request

NOTE: If the "alert_rule+user" combination is successfully deleted, the Raw response field is going to be empty.