Get a threshold notification

curl --request POST \
  --url https://api.metronome.com/v1/customer-alerts/get \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1",
  "alert_id": "8deed800-1b7a-495d-a207-6c52bac54dc9"
}
'

{
  "data": {
    "customer_status": "in_alarm",
    "alert": {
      "id": "8deed800-1b7a-495d-a207-6c52bac54dc9",
      "uniqueness_key": "823j7fqzo1",
      "name": "Low credit balance alert",
      "type": "low_credit_balance_reached",
      "status": "enabled",
      "credit_type": {
        "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
        "name": "USD (cents)"
      },
      "threshold": 0,
      "updated_at": "2022-01-01T00:00:00Z"
    }
  }
}

Notifications

Get a threshold notification

Retrieve the real-time evaluation status for a specific threshold notification-customer pair. This endpoint provides instant visibility into whether a customer has triggered a threshold notification condition, enabling you to monitor account health and take proactive action based on current threshold notification states.

Use this endpoint to:

Check if a specific customer is currently violating an threshold notification (in_alarm status)
Verify threshold notification configuration details and threshold values for a customer
Monitor the evaluation state of newly created or recently modified threshold notification
Build dashboards or automated workflows that respond to specific threshold notification conditions
Validate threshold notification behavior before deploying to production customers
Integrate threshold notification status checks into customer support tools or admin interfaces

Key response fields:

A CustomerAlert object containing:

customer_status: The current evaluation state
ok - Customer is within acceptable thresholds
in_alarm - Customer has breached the threshold for the notification
evaluating - Notification is currently being evaluated (typically during initial setup)
null - Notification has been archived
triggered_by: Additional context about what caused the notification to trigger (when applicable)
alert: Complete threshold notification configuration including:
- Notification ID, name, and type
- Current threshold values and credit type information
- Notification status (enabled, disabled, or archived)
- Last update timestamp
- Any applied filters (credit grant types, custom fields, group values)

Usage guidelines:

Customer status: Returns the current evaluation state, not historical data. For threshold notification history, use webhook notifications or event logs
Required parameters: Both customer_id and alert_id must be valid UUIDs that exist in your organization
Archived notifications: Returns null for customer_status if the notification has been archived, but still includes the notification configuration details
Performance considerations: This endpoint queries live evaluation state, making it ideal for real-time monitoring but not for bulk status checks
Integration patterns: Best used for on-demand status checks in response to user actions or as part of targeted monitoring workflows
Error handling: Returns 404 if either the customer or alert_id doesn’t exist or isn’t accessible to your organization

POST

customer-alerts

get

Get a threshold notification

curl --request POST \
  --url https://api.metronome.com/v1/customer-alerts/get \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1",
  "alert_id": "8deed800-1b7a-495d-a207-6c52bac54dc9"
}
'

{
  "data": {
    "customer_status": "in_alarm",
    "alert": {
      "id": "8deed800-1b7a-495d-a207-6c52bac54dc9",
      "uniqueness_key": "823j7fqzo1",
      "name": "Low credit balance alert",
      "type": "low_credit_balance_reached",
      "status": "enabled",
      "credit_type": {
        "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
        "name": "USD (cents)"
      },
      "threshold": 0,
      "updated_at": "2022-01-01T00:00:00Z"
    }
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The customer ID and notification ID of the threshold notification to get

customer_id

string<uuid>

required

The Metronome ID of the customer

alert_id

string<uuid>

required

The Metronome ID of the threshold notification

group_values

object[]

Only present for spend_threshold_reached notifications. Retrieve the notification for a specific group key-value pair.

Show child attributes

group_values.key

string

required

group_values.value

string

required

seat_filter

object

Only allowed for low_remaining_seat_balance_reached notifications. This filters alerts by the seat group key-value pair.

Show child attributes

seat_filter.seat_group_key

string

required

The seat group key (e.g., "seat_id", "user_id")

seat_filter.seat_group_value

string

required

The specific seat identifier to filter by

Response

Success

data

object

required

Show child attributes

data.customer_status

enum<string> | null

required

The status of the threshold notification. If the notification is archived, null will be returned.

Available options:

ok,

in_alarm,

evaluating

data.alert

object

required

Show child attributes

data.alert.id

string

required

the Metronome ID of the threshold notification

data.alert.name

string

required

Name of the threshold notification

data.alert.type

enum<string>

required

Type of the threshold notification

Available options:

spend_threshold_reached,

monthly_invoice_total_spend_threshold_reached,

low_remaining_days_for_commit_segment_reached,

low_remaining_commit_balance_reached,

low_remaining_commit_percentage_reached,

low_remaining_days_for_contract_credit_segment_reached,

low_remaining_contract_credit_balance_reached,

low_remaining_contract_credit_percentage_reached,

low_remaining_contract_credit_and_commit_balance_reached,

low_remaining_seat_balance_reached,

invoice_total_reached

data.alert.status

enum<string>

required

Status of the threshold notification

Available options:

enabled,

archived,

disabled

data.alert.threshold

number

required

Threshold value of the notification policy

data.alert.updated_at

string<date-time>

required

Timestamp for when the threshold notification was last updated

data.alert.uniqueness_key

string

Prevents the creation of duplicates. If a request to create a record is made with a previously used uniqueness key, a new record will not be created and the request will fail with a 409 error.

Required string length: 1 - 128

data.alert.credit_type

object

Show child attributes

data.alert.credit_type.name

string

required

data.alert.credit_type.id

string<uuid>

required

data.alert.credit_grant_type_filters

string[]

An array of strings, representing a way to filter the credit grant this threshold notification applies to, by looking at the credit_grant_type field on the credit grant. This field is only defined for CreditPercentage and CreditBalance notifications

data.alert.custom_field_filters

object[]

A list of custom field filters for notification types that support advanced filtering

Show child attributes

data.alert.custom_field_filters.entity

enum<string>

required

Available options:

Contract,

Commit,

ContractCredit

data.alert.custom_field_filters.key

string

required

data.alert.custom_field_filters.value

string

required

data.alert.invoice_types_filter

string[]

Only supported for invoice_total_reached threshold notifications. A list of invoice types to evaluate.

data.alert.group_values

object[]

Only present for spend_threshold_reached notifications. Scope notification to a specific group key on individual line items.

Show child attributes

data.alert.group_values.key

string

required

data.alert.group_values.value

string

data.alert.seat_filter

object

Only present for low_remaining_seat_balance_reached notifications. The seat group key or seat group key-value pair the alert is scoped to.

Show child attributes

data.alert.seat_filter.seat_group_key

string

required

The seat group key (e.g., "seat_id", "user_id") that the alert is scoped to.

data.alert.seat_filter.seat_group_value

string

The seat group value that the alert is scoped to.

data.triggered_by

string | null

If present, indicates the reason the threshold notification was triggered.

Create a threshold notification

Get all threshold notifications

⌘I

GET STARTED

ESSENTIALS

ENDPOINTS

Get a threshold notification

Use this endpoint to:

Key response fields:

Usage guidelines:

Authorizations

Body

Response