[Alerts](https://docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)
openapi: 3.0.1
info:
title: Metronome Alerts API
version: 1.0.0
description: '[Alerts](https://docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)'
servers:
- url: https://api.metronome.com
description: Production server
security:
- bearerAuth: []
tags:
- name: Alerts
description: '[Alerts](https://docs.metronome.com/connecting-metronome/alerts/) monitor customer spending, balances, and other billing factors. Use these endpoints to create, retrieve, and archive customer alerts. To view sample alert payloads by alert type, navigate [here.](https://docs.metronome.com/manage-product-access/create-manage-alerts/#webhook-notifications)'
paths:
/v1/alerts/archive:
post:
description: 'Permanently disable a threshold notification and remove it from active monitoring across all customers. Archived threshold notifications stop evaluating immediately and can optionally release their uniqueness key for reuse in future threshold notification configurations.
### Use this endpoint to:
- Decommission threshold notifications that are no longer needed
- Clean up test or deprecated threshold notification configurations
- Free up uniqueness keys for reuse with new threshold notifications
- Stop threshold notification evaluations without losing historical configuration data
- Disable outdated monitoring rules during pricing model transitions
### Key response fields:
- data: Object containing the archived threshold notification''s ID
### Usage guidelines:
- Irreversible for evaluation: Archived threshold notifications cannot be re-enabled; create a new threshold notification to resume monitoring
- Uniqueness key handling: Set `release_uniqueness_key` : `true` to reuse the key in future threshold notifications
- Immediate effect: Threshold notification evaluation stops instantly across all customers
- Historical preservation: Archive operation maintains threshold notification history and configuration for compliance and auditing
'
operationId: archiveAlert-v1
summary: Archive a threshold notification
tags:
- Alerts
requestBody:
description: The ID of the threshold notification to archive
content:
application/json:
schema:
$ref: '#/components/schemas/ArchiveAlertPayload'
example:
id: 8deed800-1b7a-495d-a207-6c52bac54dc9
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Id'
example:
data:
id: 8deed800-1b7a-495d-a207-6c52bac54dc9
'404':
$ref: '#/components/responses/NotFound'
/v1/alerts/create:
post:
description: "Create a new threshold notification to monitor customer spending, balances, and billing metrics in real-time. Metronome's notification system provides industry-leading speed with immediate evaluation capabilities, enabling you to proactively manage customer accounts and prevent revenue leakage.\n\nThis endpoint creates configurable threshold notifications that continuously monitor various billing thresholds including spend limits, credit balances, commitment utilization, and invoice totals. Threshold notifications can be configured globally for all customers or targeted to specific customer accounts.\n\n### Use this endpoint to:\n- Proactively monitor customer spending patterns to prevent unexpected overages or credit exhaustion\n- Automate notifications when customers approach commitment limits or credit thresholds\n- Enable real-time intervention for accounts at risk of churn or payment issues\n- Scale billing operations by automating threshold-based workflows and notifications\n\n### Key response fields: \nA successful response returns a CustomerAlert object containing:\n\n- The threshold notification configuration with its unique ID and current status\n- The customer's evaluation status (ok, in_alarm, or evaluating)\n- Threshold notification metadata including type, threshold values, and update timestamps\n\n### Usage guidelines:\n- Immediate evaluation: Set `evaluate_on_create` : `true` (default) for instant evaluation against existing customers\n- Uniqueness constraints: Each threshold notification must have a unique `uniqueness_key` within your organization. Use `release_uniqueness_key` : `true` when archiving to reuse keys\n- Notification type requirements: Different threshold notification types require specific fields (e.g., `billable_metric_id` for usage notifications, `credit_type_id` for credit-based threshold notifications)\n- Webhook delivery: Threshold notifications trigger webhook notifications for real-time integration with your systems. Configure webhook endpoints before creating threshold notifications\n- Performance at scale: Metronome's event-driven architecture processes threshold notification evaluations in real-time as usage events stream in, unlike competitors who rely on periodic polling or batch evaluation cycles\n"
operationId: createAlert-v1
summary: Create a threshold notification
tags:
- Alerts
requestBody:
description: The details of the threshold notification to create
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCustomerAlertPayload'
example:
alert_type: spend_threshold_reached
credit_type_id: 2714e483-4ff1-48e4-9e25-ac732e8f24f2
name: $100 spend threshold reached
threshold: 10000
customer_id: 4db51251-61de-4bfe-b9ce-495e244f3491
credit_grant_type_filters:
- enterprise
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/Id'
example:
data:
id: 58fb0650-e54a-4d17-93cb-ba8e56c32c65
/v1/customer-alerts/get:
post:
description: "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.\n\n### Use this endpoint to:\n- Check if a specific customer is currently violating an threshold notification (`in_alarm` status)\n- Verify threshold notification configuration details and threshold values for a customer\n- Monitor the evaluation state of newly created or recently modified threshold notification\n- Build dashboards or automated workflows that respond to specific threshold notification conditions\n- Validate threshold notification behavior before deploying to production customers\n- Integrate threshold notification status checks into customer support tools or admin interfaces\n\n### Key response fields: \nA CustomerAlert object containing:\n\n- `customer_status`: The current evaluation state\n\n- `ok` - Customer is within acceptable thresholds\n- `in_alarm` - Customer has breached the threshold for the notification\n- `evaluating` - Notification is currently being evaluated (typically during initial setup)\n- `null` - Notification has been archived\n- `triggered_by`: Additional context about what caused the notification to trigger (when applicable)\n- alert: Complete threshold notification configuration including:\n - Notification ID, name, and type\n - Current threshold values and credit type information\n - Notification status (enabled, disabled, or archived)\n - Last update timestamp\n - Any applied filters (credit grant types, custom fields, group values)\n\n### Usage guidelines:\n- Customer status: Returns the current evaluation state, not historical data. For threshold notification history, use webhook notifications or event logs\n- Required parameters: Both customer_id and alert_id must be valid UUIDs that exist in your organization\n- Archived notifications: Returns null for customer_status if the notification has been archived, but still includes the notification configuration details\n- Performance considerations: This endpoint queries live evaluation state, making it ideal for real-time monitoring but not for bulk status checks\n- Integration patterns: Best used for on-demand status checks in response to user actions or as part of targeted monitoring workflows\n- Error handling: Returns 404 if either the customer or alert_id doesn't exist or isn't accessible to your organization\n"
operationId: getCustomerAlert-v1
summary: Get a threshold notification
tags:
- Alerts
requestBody:
description: The customer ID and notification ID of the threshold notification to get
content:
application/json:
schema:
$ref: '#/components/schemas/GetCustomerAlertPayload'
example:
customer_id: 9b85c1c1-5238-4f2a-a409-61412905e1e1
alert_id: 8deed800-1b7a-495d-a207-6c52bac54dc9
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
properties:
data:
$ref: '#/components/schemas/CustomerAlert'
example:
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'
'404':
$ref: '#/components/responses/NotFound'
/v1/customer-alerts/list:
post:
description: "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.\n\n### Use this endpoint to:\n- Display all active threshold notifications for a customer in dashboards or admin panels\n- Quickly identify which threshold notifications a customer is currently triggering\n- Audit threshold notification coverage for specific accounts\n- Filter threshold notifications by status (enabled, disabled, or archived)\n\n### Key response fields:\n- data: Array of CustomerAlert objects, each containing:\n - Current evaluation status (`ok`, `in_alarm`, `evaluating`, or `null`)\n - Complete threshold notification configuration and threshold details\n - Threshold notification metadata including type, name, and last update time\n- next_page: Pagination cursor for retrieving additional results\n\n### Usage guidelines:\n- Default behavior: Returns only enabled threshold notifications unless `alert_statuses` filter is specified\n- Pagination: Use the `next_page` cursor to retrieve all results for customers with many notifications\n- Performance: Efficiently retrieves multiple threshold notification statuses in a single request instead of making individual calls\n- Filtering: Pass the `alert_statuses` array to include disabled or archived threshold notifications in results\n"
operationId: listCustomerAlerts-v1
summary: Get all threshold notifications
parameters:
- $ref: '#/components/parameters/NextPage'
tags:
- Alerts
requestBody:
description: The threshold notifications query to run
content:
application/json:
schema:
$ref: '#/components/schemas/ListCustomerAlertsPayload'
example:
customer_id: 9b85c1c1-5238-4f2a-a409-61412905e1e1
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
required:
- data
- next_page
properties:
data:
type: array
items:
$ref: '#/components/schemas/CustomerAlert'
next_page:
type: string
nullable: true
example:
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
/v1/customer-alerts/reset:
post:
description: "Force an immediate re-evaluation of a specific threshold notification for a customer, clearing any previous state and triggering a fresh assessment against current thresholds. This endpoint ensures threshold notification accuracy after configuration changes or data corrections.\n\n### Use this endpoint to:\n- Clear false positive threshold notifications after fixing data issues\n- Re-evaluate threshold notifications after adjusting customer balances or credits\n- Test threshold notification behavior during development and debugging\n- Resolve stuck threshold notification that may be in an incorrect state\n- Trigger immediate evaluation after threshold modifications\n\n### Key response fields: \n- 200 Success: Confirmation that the threshold notification has been reset and re-evaluation initiated\n- No response body is returned - the operation completes asynchronously\n\n### Usage guidelines:\n- Immediate effect: Triggers re-evaluation instantly, which may result in new webhook notifications if thresholds are breached\n- State clearing: Removes any cached evaluation state, ensuring a fresh assessment\n- Use sparingly: Intended for exceptional cases, not routine operations\n- Asynchronous processing: The reset completes immediately, but re-evaluation happens in the background\n"
operationId: resetCustomerAlerts-v1
summary: Reset a threshold notification
tags:
- Alerts
requestBody:
description: The customer ID and notification ID of the threshold notification to reset
content:
application/json:
schema:
$ref: '#/components/schemas/ResetCustomerAlertsPayload'
example:
alert_id: 5e8691bf-b22a-4672-922d-f80eee940f01
customer_id: 4c83caf3-8af4-44e2-9aeb-e290531726d9
responses:
'200':
description: Success
components:
schemas:
UniquenessKey:
type: string
minLength: 1
maxLength: 128
description: 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.
CreditType:
required:
- name
- id
type: object
properties:
name:
type: string
id:
type: string
format: uuid
GetCustomerAlertPayload:
required:
- customer_id
- alert_id
type: object
properties:
customer_id:
type: string
format: uuid
description: The Metronome ID of the customer
alert_id:
type: string
format: uuid
description: The Metronome ID of the threshold notification
plans_or_contracts:
x-mint:
groups:
- ff:plans-contracts-parallel-alerts
type: string
enum:
- PLANS
- CONTRACTS
description: When parallel threshold notifications are enabled during migration, this flag denotes whether to fetch notifications for plans or contracts.
group_values:
type: array
description: Only present for `spend_threshold_reached` notifications. Retrieve the notification for a specific group key-value pair.
items:
$ref: '#/components/schemas/GroupKeyFilterType'
seat_filter:
type: object
description: Only allowed for `low_remaining_seat_balance_reached` notifications. This filters alerts by the seat group key-value pair.
required:
- seat_group_key
- seat_group_value
properties:
seat_group_key:
type: string
description: The seat group key (e.g., "seat_id", "user_id")
seat_group_value:
type: string
description: The specific seat identifier to filter by
GroupValueFilterType:
type: object
required:
- key
properties:
key:
type: string
value:
type: string
GroupKeyFilterType:
type: object
description: Scopes threshold notification evaluation to a specific presentation group key on individual line items. Only present for spend notifications.
required:
- key
- value
properties:
key:
type: string
value:
type: string
InvoiceTypesFilterType:
type: array
description: Only supported for invoice_total_reached threshold notifications. A list of invoice types to evaluate.
items:
$ref: '#/components/schemas/InvoiceType'
Error:
required:
- message
type: object
properties:
message:
type: string
ArchiveAlertPayload:
required:
- id
type: object
properties:
id:
type: string
format: uuid
description: The Metronome ID of the threshold notification
release_uniqueness_key:
type: boolean
description: If true, resets the uniqueness key on this threshold notification so it can be re-used
Id:
required:
- id
type: object
properties:
id:
type: string
format: uuid
CreateCustomerAlertPayload:
required:
- alert_type
- name
- threshold
type: object
properties:
alert_type:
type: string
enum:
- spend_threshold_reached
- monthly_invoice_total_spend_threshold_reached
- usage_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
- invoice_total_reached
- low_remaining_seat_balance_reached
description: Type of the threshold notification
name:
type: string
description: Name of the threshold notification
uniqueness_key:
$ref: '#/components/schemas/UniquenessKey'
threshold:
type: number
description: Threshold value of the notification policy. Depending upon the notification type, this number may represent a financial amount, the days remaining, or a percentage reached.
credit_type_id:
type: string
format: uuid
description: ID of the credit's currency, defaults to USD. If the specific notification type requires a pricing unit/currency, find the ID in the [Metronome app](https://app.metronome.com/offering/pricing-units).
customer_id:
type: string
format: uuid
description: If provided, will create this threshold notification for this specific customer. To create a notification for all customers, do not specify a `customer_id`.
billable_metric_id:
type: string
format: uuid
description: For threshold notifications of type `usage_threshold_reached`, specifies which billable metric to track the usage for.
credit_grant_type_filters:
type: array
items:
type: string
description: 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
evaluate_on_create:
type: boolean
description: If true, the threshold notification will evaluate immediately on customers that already meet the notification threshold. If false, it will only evaluate on future customers that trigger the threshold. Defaults to true.
custom_field_filters:
type: array
description: A list of custom field filters for threshold notification types that support advanced filtering. Only present for contract invoices.
items:
$ref: '#/components/schemas/CustomFieldFilterType'
invoice_types_filter:
$ref: '#/components/schemas/InvoiceTypesFilterType'
group_values:
type: array
description: Only present for `spend_threshold_reached` notifications. Scope notification to a specific group key on individual line items.
items:
$ref: '#/components/schemas/GroupValueFilterType'
seat_filter:
type: object
description: Required for `low_remaining_seat_balance_reached` notifications. The alert is scoped to this seat group key-value pair.
required:
- seat_group_key
properties:
seat_group_key:
type: string
description: The seat group key (e.g., "seat_id", "user_id")
seat_group_value:
type: string
description: Optional seat identifier the alert is scoped to.
InvoiceType:
type: string
example: SCHEDULED or USAGE
ListCustomerAlertsPayload:
required:
- customer_id
type: object
properties:
customer_id:
type: string
format: uuid
description: The Metronome ID of the customer
alert_statuses:
type: array
minItems: 1
items:
type: string
enum:
- enabled
- disabled
- archived
- ENABLED
- DISABLED
- ARCHIVED
- Enabled
- Disabled
- Archived
description: Optionally filter by threshold notification status. If absent, only enabled notifications will be returned.
Alert:
required:
- id
- name
- type
- status
- threshold
- updated_at
type: object
properties:
id:
type: string
description: the Metronome ID of the threshold notification
name:
type: string
description: Name of the threshold notification
uniqueness_key:
$ref: '#/components/schemas/UniquenessKey'
type:
type: string
enum:
- 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
description: Type of the threshold notification
status:
type: string
enum:
- enabled
- archived
- disabled
description: Status of the threshold notification
credit_type:
$ref: '#/components/schemas/CreditType'
nullable: true
threshold:
type: number
description: Threshold value of the notification policy
updated_at:
type: string
format: date-time
description: Timestamp for when the threshold notification was last updated
credit_grant_type_filters:
type: array
items:
type: string
description: 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
custom_field_filters:
type: array
description: A list of custom field filters for notification types that support advanced filtering
items:
$ref: '#/components/schemas/CustomFieldFilterType'
group_key_filter:
x-mint:
groups:
- client_id:462b838b-1582-4100-816e-f6c07bb604fe
- client_id:c187f54f-e807-4cf6-8fa1-a01f09d05412
- client_id:aa2899ec-16ad-413b-b20b-ec9ba4692d4e
- client_id:2f0c6751-0b61-46f2-8664-2eb1be6136cf
- client_id:b2c5d30a-6078-4cd4-9e98-340ca0883789
- client_id:67c6fe5e-5715-4b05-aa2a-b3885cd68b81
- client_id:f9b1ebc0-19f5-43cd-ba0b-7cf7da34fe7c
- client_id:98ac66cc-88b4-447f-a2e6-a84ebc81e36a
$ref: '#/components/schemas/GroupKeyFilterType'
invoice_types_filter:
$ref: '#/components/schemas/InvoiceTypesFilterType'
group_values:
type: array
description: Only present for `spend_threshold_reached` notifications. Scope notification to a specific group key on individual line items.
items:
$ref: '#/components/schemas/GroupValueFilterType'
seat_filter:
type: object
description: Only present for low_remaining_seat_balance_reached notifications. The seat group key or seat group key-value pair the alert is scoped to.
required:
- seat_group_key
properties:
seat_group_key:
type: string
description: The seat group key (e.g., "seat_id", "user_id") that the alert is scoped to.
seat_group_value:
type: string
description: The seat group value that the alert is scoped to.
CustomFieldFilterType:
type: object
required:
- entity
- key
- value
properties:
entity:
type: string
enum:
- Contract
- Commit
- ContractCredit
key:
type: string
value:
type: string
ResetCustomerAlertsPayload:
required:
- customer_id
- alert_id
type: object
properties:
customer_id:
type: string
format: uuid
description: The Metronome ID of the customer
alert_id:
type: string
format: uuid
description: The Metronome ID of the threshold notification
CustomerAlert:
required:
- customer_status
- alert
type: object
properties:
customer_status:
type: string
enum:
- ok
- in_alarm
- evaluating
nullable: true
description: The status of the threshold notification. If the notification is archived, null will be returned.
triggered_by:
type: string
nullable: true
description: If present, indicates the reason the threshold notification was triggered.
alert:
$ref: '#/components/schemas/Alert'
responses:
NotFound:
description: The specified resource was not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
parameters:
NextPage:
name: next_page
in: query
description: Cursor that indicates where the next page of results should start.
required: false
schema:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer