Get all threshold notifications

curl --request POST \
  --url https://api.metronome.com/v1/customer-alerts/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1"
}
'

{
  "data": [
    {
      "customer_status": "in_alarm",
      "alert": {
        "id": "8deed800-1b7a-495d-a207-6c52bac54dc9",
        "name": "Low credit balance alert",
        "uniqueness_key": "823j7fqzo1",
        "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"
      }
    },
    {
      "customer_status": "ok",
      "alert": {
        "id": "3d45fdc3-e237-4acd-a7d9-ccfeb40e71b8",
        "name": "Spend threshold alert",
        "type": "spend_threshold_reached",
        "status": "enabled",
        "credit_type": {
          "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
          "name": "USD (cents)"
        },
        "threshold": 1000,
        "updated_at": "2022-01-01T00:00:00Z"
      }
    }
  ],
  "next_page": null
}

Notifications

Get all threshold notifications

Retrieve all threshold notification configurations and their current statuses for a specific customer in a single API call. This endpoint provides a comprehensive view of all threshold notification monitoring a customer account.

Use this endpoint to:

Display all active threshold notifications for a customer in dashboards or admin panels
Quickly identify which threshold notifications a customer is currently triggering
Audit threshold notification coverage for specific accounts
Filter threshold notifications by status (enabled, disabled, or archived)

Key response fields:

data: Array of CustomerAlert objects, each containing:
- Current evaluation status (ok, in_alarm, evaluating, or null)
- Complete threshold notification configuration and threshold details
- Threshold notification metadata including type, name, and last update time
next_page: Pagination cursor for retrieving additional results

Usage guidelines:

Default behavior: Returns only enabled threshold notifications unless alert_statuses filter is specified
Pagination: Use the next_page cursor to retrieve all results for customers with many notifications
Performance: Efficiently retrieves multiple threshold notification statuses in a single request instead of making individual calls
Filtering: Pass the alert_statuses array to include disabled or archived threshold notifications in results

POST

customer-alerts

list

Get all threshold notifications

curl --request POST \
  --url https://api.metronome.com/v1/customer-alerts/list \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "9b85c1c1-5238-4f2a-a409-61412905e1e1"
}
'

{
  "data": [
    {
      "customer_status": "in_alarm",
      "alert": {
        "id": "8deed800-1b7a-495d-a207-6c52bac54dc9",
        "name": "Low credit balance alert",
        "uniqueness_key": "823j7fqzo1",
        "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"
      }
    },
    {
      "customer_status": "ok",
      "alert": {
        "id": "3d45fdc3-e237-4acd-a7d9-ccfeb40e71b8",
        "name": "Spend threshold alert",
        "type": "spend_threshold_reached",
        "status": "enabled",
        "credit_type": {
          "id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
          "name": "USD (cents)"
        },
        "threshold": 1000,
        "updated_at": "2022-01-01T00:00:00Z"
      }
    }
  ],
  "next_page": null
}

Authorizations

Authorization

string

header

required

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

Query Parameters

next_page

string

Cursor that indicates where the next page of results should start.

Body

application/json

The threshold notifications query to run

customer_id

string<uuid>

required

The Metronome ID of the customer

alert_statuses

enum<string>[]

Optionally filter by threshold notification status. If absent, only enabled notifications will be returned.

Minimum array length: 1

Available options:

enabled,

disabled,

archived,

ENABLED,

DISABLED,

ARCHIVED,

Enabled,

Disabled,

Archived

Response

200 - application/json

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.

next_page

string | null

required

Get a threshold notification

Reset a threshold notification

⌘I

GET STARTED

ESSENTIALS

ENDPOINTS

Get all threshold notifications

Use this endpoint to:

Key response fields:

Usage guidelines:

Authorizations

Query Parameters

Body

Response