Alerts API

This article provides sample API calls for retrieving triggered Alerts, creating and updating Alert Rules, and managing User subscriptions to Alert Rules:

  • /api/metric_alert: Retrieve triggered Alerts for a Metric, dismiss, activate, re-send, or send the Alert to phone.
  • /api/alert_rule/: Retrieve, create, and update Alert Rules.
  • /api/alert_rule_user_share: Retrieve User Alerts, subscribe, and unsubscribe User from Alerts.

Prerequisites:

Table of Contents

  1. Access Admin > System > API Toolkit
  2. Configure Triggered Alerts
    1. Retrieve Triggered Alerts for a Metric
    2. Act on a Triggered Alert
  3. Configure Alert Rules
    1. Retrieve Alert Rules
    2. Create or Update an Alert Rule
  4. Manage User Subscriptions to Alert Rules
    1. View User Subscriptions
    2. Subscribe a User to an Alert Rule
    3. Unsubscribe a User from an Alert Rule

1. Access Admin > System > API Toolkit

2. Configure Triggered Alerts

2.1. Retrieve Triggered Alerts for a Metric

A GET request to /api/metric_alert returns the alerts that have fired for a Metric.

NOTE: The result may be empty if no alerts have triggered.

  1. Item: metric_alert
  2. Method: GET
  3. Filter the results with the following parameters:
    • element: The element (Metric) ID. Find it in the element editor URL:
https://docs.metricinsights.com/editor/element/metric/152743#data
  • dimension_value: (Optional) The Dimension Value ID to filter by.
  • start_time / end_time: (Optional) Restrict alerts to a date range. Accepts YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.
  1. Enter an API Token.
  2. [Run request]

Example Response 

{
  "metric_alerts": [
    {
      "id": 90187,
      "element": 284,
      "dimension_value": -1,
      "alert_rule": 1442,
      "text": "Revenue is above the target of 1,000,000",
      "measurement_time": "2026-06-01 00:00:00",
      "alert_status": "Active"
    }
  ]
}

Fields Description

Field NameValue TypeDescription
id
integerThe ID of the triggered alert (alert event).
element
integerThe element (Metric) ID.
dimension_value
integerThe Dimension Value ID. -1 represents all Dimension Values.
alert_rule
integerThe ID of the Alert Rule that fired.
text
stringThe alert message text.
measurement_time
datetimeThe measurement time the alert is associated with.
alert_status
stringThe alert's status. ("Active", "Dismissed")

NOTES:

  • Add html="Y" to also return a text_html field, or json="Y" to return the raw alert payload as JSON.
  • Add visualization_source="Y" to include dimension_name, alert_rule_name, and visualization-source fields.

2.2. Act on a Triggered Alert

A PUT request to /api/metric_alert/id/<id> performs an action on a triggered alert. The action is specified with the call parameter.

  1. Item: metric_alert
  2. Method: PUT
  3. Enter the Alert Event ID
  4. call: The action to perform:
    • dismiss: Dismiss the alert for the current user.
    • activate: Re-activate a dismissed alert.
    • resend: Resend the alert (Admin only).
    • send_to_phone: Send the alert as a mobile notification. Optional report (report ID); Admins may also pass user to send on another user's behalf.
  5. Enter an API Token.
  6. [Run request]

3. Configure Alert Rules

3.1. Retrieve Alert Rules

A GET request to /api/alert_rule returns the configured Alert Rules.

  1. Item: alert_rule
  2. Method: GET
  3. Filter the results with the following parameters:
    • element: Return rules for this element (Metric) ID.
    • report: Return rules for this report ID.
    • personal: Set to "Y" to return only personal (KPI) alert rules.
  4. Enter an API Token.
  5. [Run request]

The response lists each rule's id, name, element, report, alert_rule_type, type, and condition fields (see the parameter table in the Create or Update an Alert Rule section), plus last_updated_time and creator.

3.2. Create or Update an Alert Rule

  • A POST request to /api/alert_rule creates a new Alert Rule.
  • A PUT request to /api/alert_rule/id/<id> updates an existing rule.
  1. Item: alert_rule
  2. Method: Select POST to create a new, or PUT to update an exsiting  Alert Rule.
  3. Enter the existing Alert Rule ID (for POST), or the ID of the Alert Rule that needs to be updated (for PUT).
  4. Select JSON request and enter values.
  5. Enter an API Token.
  6. [Run request]

Alert Rule Types and Fields

This table displays available Alert Rule Types (alert_rule_type) and condition types that trigger the Alers (type).

alert_rule_typeSupported type values
user (KPI)fixed value, prior value, average, volatility band, target, compound
global (Global)fixed value, prior value, average, volatility band, stoplight, unusual value, best ever, worst ever
Field NameTypeDescription
namestringA unique, user-defined name for the alert.
elementintegerThe element (Metric) ID the alert is created for.
reportintegerThe report ID the alert is created for.
typeenumThe condition type that triggers the alert.
  • See the table above for details on available condition types.
alert_rule_typeenumKPI vs Global alert.
alert_visibilityenumWhether the alert is visible to everyone with access to the Metric, or only to the current user.
assign_typeenumThe entity the alert is assigned to.
send_alert_to_phoneenumSend the alert as a mobile notification. (Y, N)
comparison_typeenumThe comparison that triggers the alert. (fixed, pct variance, less fixed, less pct variance)
comparison_interval_compare_to_periodenumThe period to compare to. (hour, day, week, month, quarter, year)
comparison_interval_periodenumThe period whose values are compared. (hour, day, week, month, quarter, year)
comparison_intervalintegerHow many comparison periods to consider.
percentage_comparison_typeenumPercentage comparison operator. (above, above or equal, below, below or equal, above or below, within, between, equal)
comparison_fixed_valuefloatThe fixed value the condition is applied to.
comparison_fixed_value_upper_boundfloatThe upper bound of a value range.
comparison_percentage_tolerancefloatThe percentage above/below which the alert is created.
range_of_values_scopeenumThe value condition for the alert. (above, below, above or below)
compare_lineintegerThe compare line ID.
targetintegerThe Target ID. Required for type = target.
immediate_notification_indenum"Y" = send immediately, "N" = email digest, "None" = browser only.
send_notification_viaenumHow the notification is sent. (email, sms, phone_alert)
trigger_alert_whenenumWhen the alert is sent. (first time only, every time)

4. Manage User Subscriptions to Alert Rules

The /api/alert_rule_user_share endpoint manages which Users are subscribed to which Alert Rules. Each record represents a single User-to-Alert-Rule subscription.

4.1. View User Subscriptions

  • A GET request to /api/alert_rule_user_share returns the Alert Rule-to-User subscription mappings.
  • A GET request to /api/alert_rule_user_share/id/<id> returns the specified Alert Rue-to-User mapping.
  1. Item: alert_rule_user_share
  2. Method: GET
  3. Filter the results with the following parameters:
    • alert_rule: The ID of the Alert Rule.
    • user: The ID of the User.
    • Leave both empty to return all mappings.
  4. Enter an API Token.
  5. [Run request]

4.2. Subscribe a User to an Alert Rule

A POST request to /api/alert_rule_user_share subscribes a User to an Alert Rule.

  1. Item: alert_rule_user_share
  2. Method: POST
  3. Enter the ID of an already existing Aler Rule-to-User mapping.
  4. Choose JSON request and provide the following values:
    • alert_rule: The Alert Rule ID
    • user: The User ID
  5. Enter an API Token.
  6. [Run request]

4.3. Unsubscribe a User from an Alert Rule

A DELETE request to /api/alert_rule_user_share/id/<id> removes a User's subscription to an Alert Rule.

  1. Item: alert_rule_user_share
  2. Method: DELETE
  3. Enter the ID of the subscription to be deleted.
  4. Enter an API Token.
  5. [Run request]