Skip to main content
Metronome enables you to configure certain alerts with more granular inclusion and exclusion conditions using alert specifiers. By default, a low_remaining_contract_credit_and_commit_balance_reached alert evaluates the combined balance of all active commits and credits for a customer. When that total drops below the configured threshold, you receive a single notification. With alert specifiers, you can change what gets evaluated:
  • Include only commits and credits that match a specific set of custom field key values
  • Exclude commits and credits that match certain custom field conditions
  • Group balance evaluations by a custom field key, so you receive a separate notification for each unique value of that key
This enables patterns like:
  • Fire an alert when the balance of product-specific credits (e.g., credits tagged product_family: abc) falls below a threshold, independently of your general credit pool
  • Fire an alert when an individual commit (e.g., commits tagged with unique_id: commit_xyz) falls below a threshold
  • Exclude certain perpetual credits from a general balance alert so it only fires when your standard credits are low

​
How alert specifiers work

Alert specifiers are defined in the alert_specifiers array on a low_remaining_contract_credit_and_commit_balance_reached alert. Each specifier contains:
  • custom_field_filters: An array of inclusion conditions that define which commits and credits count toward this alert. If omitted, all commits and credits are included. If a key is specified without a value, the alert groups evaluations by each unique value of that key.
  • exclude: An array of exclusion conditions. Commits and credits matching any exclusion condition are removed from the evaluation, even if they satisfy the inclusion conditions.
Alert specifiers filter on custom fields. You can set custom fields on any commit or credit upon creation. Read more setting and viewing custom fields here. Setting or updating a custom field value on a credit or commit will trigger a re-evaluation of any balance alert using alert_specifiers applicable to that credit or commit.

​
Include specified key-value pairs

When you provide custom_field_filters with a specific key and value, only commits and credits matching all of those conditions are counted toward the alert threshold. Multiple specifiers in the alert_specifiers array are evaluated as OR conditions — a commit or credit needs to match only one specifier to be included. Within a single specifier’s custom_field_filters array, multiple conditions are evaluated as AND — a commit or credit must match all listed conditions to be included.
ALERT SPECIFIERS VS. CUSTOM FIELD FILTERSalert_specifiers[].custom_field_filter with a specific key and value functions identically to the top-level custom_field_filter when creating an alert. Use alert_specifiers for greater flexibility.
Imagine you are granting a free credit promo on May 4th for a subset of customers and want to know when a customer’s promotional credits reach $0. Create an alert that fires only when credits tagged promo_code: may_the_fourth reach a $0 threshold. 
POST /v1/alerts/create
{
  "name": "May the Fourth be with you promo alert",
  "alert_type": "low_remaining_contract_credit_and_commit_balance_reached",
  "threshold": 0,
  "alert_specifiers": [
    {
      "custom_field_filters": [
         {
            "entity": "ContractCredit",
            "key": "promo_code",
            "value": "may_the_fourth"
          }
       ]
    }
  ]
}

​
Include all unique values of a specified key

When you provide a custom_field_filters entry with a key but no value, Metronome evaluates the balance separately for each unique value of that key. A webhook is sent if the total balance for all balances tagged with the one custom field key-value pair is below the notification threshold, and subsequently when any other groups of balances with the same key but different values meet the threshold. An initial top-level webhook will be sent the first time any key-value pair with the defined key reaches the threshold.
ONE GROUP KEY ONLYPer-key grouping requires a single specifier with a single key and no value. You cannot group by more than one key at a time.
Imagine your company offers several different promotional credits at a time. Any one customer may have multiple promotions running and wants to be alerted when each individual promotional credit reaches $0. Instead of creating a dedicated alert to each promotion, create a grouped balance alert for all promotions. 
POST /v1/alerts/create
{
  "name": "Parent promo alert",
  "alert_type": "low_remaining_contract_credit_and_commit_balance_reached",
  "threshold": 0,
  "alert_specifiers": [
    {
      "custom_field_filters": [
         {
            "entity": "ContractCreditorCommit",
            "key": "promo_code"
          }
       ]
    }
  ]
}
For each promotional credit given, create the credit with custom field key promo_code and the name of the promotion. The alert will automatically be applied to all customers and all current and future promotions without any code changes needed. When a specific promotional credit on a customer reaches the threshold, you receive a webhook for that specific key-value pair that crossed the threshold. The alert_specifiers field in the payload includes the key and value that triggered the notification. 
{
  "id": "notif_abc123",
  "type": "alerts.low_remaining_contract_credit_and_commit_balance_reached",
  "properties": {
    "customer_id": "cust_123",
    "alert_id": "alert_id",
    "alert_name": "Parent promo alert",
    "timestamp": "2026-05-07T15:08:44.865Z",
    "threshold": 0,
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "alert_specifiers": [
      {
        "custom_field_filters": [
          {
            "entity": "ContractCreditOrCommit",
            "key": "promo_code",
            "value": "may_7th_promo"
          }
        ]
      }
    ]
  }
}
If this is the first key-value pair to cross the threshold, you will also receive an additional notification for the overall alert. This webhook omits the specific value field in custom_field_filters, indicating it applies to the alert as a whole. 
{
  "id": "notif_def456",
  "type": "alerts.low_remaining_contract_credit_and_commit_balance_reached",
  "properties": {
    "customer_id": "cust_123",
    "alert_id": "alert_id",
    "alert_name": "Parent promo alert",
    "timestamp": "2026-05-07T15:08:44.866Z",
    "threshold": 0,
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "alert_specifiers": [
      {
        "custom_field_filters": [
          {
            "entity": "ContractCreditOrCommit",
            "key": "promo_code"
          }
        ]
      }
    ]
  }
}
INFOYou can set up to 3 per-key balance alerts for a single customer with support for up to 1K cardinality (unique key-value pairs) per group key. For keys with more than 1000 values, contact your Metronome representative to discuss your alert specifier configuration.

​
Exclude specified key-value pairs

The exclude field within a specifier removes specific commits or credits from an otherwise inclusive set. Multiple exclusion entries are evaluated as OR conditions — a commit or credit is excluded if it matches any one of them.
EXCLUDED ENTITIES MUST BE INCLUDED IN THE SAME SPECIFIERExclusion conditions must target entities that are within the inclusion scope of the same specifier. For example, you cannot create a single alert specifier that includes commits but excludes credits.
Create an alert that fires when the general (non-product-specific) credit balance falls below a threshold. Credits tagged is_product_specific: true are excluded from this evaluation. 
POST /v1/alerts/create
{
  "customer_id": "cust_abc123",
  "name": "General credit balance alert",
  "alert_type": "low_remaining_contract_credit_and_commit_balance_reached",
  "threshold": 10000,
  "alert_specifiers": [
    {
      "exclude": [
        {
          "custom_field_filters": [
            {
              "entity": "ContractCreditOrCommit",
              "key": "is_product_specific",
              "value": "true"
            }
          ]
        }
      ]
    }
  ]
}

​
Retrieving alert status

You can retrieve the current status of an alert with specifiers using POST /v1/customer-alerts/get. To retrieve the status of a specific custom field key-value pair, pass either custom_field_filters or alert_specifiers in the request body. 
POST /v1/customer-alerts/get
{
  "alert_id": "alert_id",
  "customer_id": "cust_123",
  "alert_specifiers": [
    {
      "custom_field_filters": [
        {
          "entity": "ContractCreditOrCommit",
          "key": "promo_code",
          "value": "may_7th_promo"
        }
      ]
    }
  ]
}
The query will return the status of the specified key-value pair: 
{
  "data": {
    "customer_status": "in_alarm",
    "alert": {
      "id": "alert_id",
      "name": "Per-product-family balance alert (excluding data compression)",
      "alert_type": "low_remaining_contract_credit_and_commit_balance_reached",
      "status": "active",
      "threshold": 0,
      "alert_specifiers": [
        {
          "custom_field_filters": [
            {
              "entity": "ContractCreditOrCommit",
		          "key": "promo_code",
			         "value": "may_7th_promo"
            }
          ]
        }
      ]
    }
  }
}

​
Resolved webhooks

Receive a low_remaining_contract_credit_and_commit_balance_resolved webhook when an alert returns to OK from IN_ALARM. Reach out to your Metronome representative if you need this enabled.