> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metronome.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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




## OpenAPI

````yaml /openapi.json post /v1/customer-alerts/list
openapi: 3.0.1
info:
  title: Metronome
  version: 1.0.0
servers:
  - url: https://api.metronome.com
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Customers
    description: >-
      [Customers](https://docs.metronome.com/provisioning/create-customers/) in
      Metronome represent your users for all billing and reporting. Use these
      endpoints to create, retrieve, update, and archive customers and their
      billing configuration.
  - name: Billable metrics
    description: >-
      [Billable
      metrics](https://docs.metronome.com/understanding-metronome/how-metronome-works#billable-metrics)
      in Metronome represent the various consumption components that Metronome
      meters and aggregates.
  - name: Usage
    description: >-
      [Usage
      events](https://docs.metronome.com/connecting-metronome/send-usage-data/)
      are the basis for billable metrics. Use these endpoints to send usage
      events to Metronome and retrieve aggregated event data.
  - name: Products
    description: Products are the items that customers purchase.
  - name: Rate cards
    description: Rate cards are used to define default pricing for products.
  - name: Contracts
    description: >-
      A contract defines a customer’s products, pricing, discounts, commitments,
      and more. Use these endpoints to create and update contracts data.
  - name: Credits and commits
    description: Credits and commits are used to manage customer balances.
  - name: Invoices
    description: >-
      [Invoices](https://docs.metronome.com/invoicing/) reflect how much a
      customer spent during a period, which is the basis for billing. Metronome
      automatically generates invoices based upon your pricing, packaging, and
      usage events. Use these endpoints to retrieve invoices.
  - 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)
  - name: Custom fields
    description: >-
      [Custom fields](https://docs.metronome.com/integrations/custom-fields/)
      enable adding additional data to Metronome entities. Use these endpoints
      to create, retrieve, update, and delete custom fields.
  - name: Security
    description: >-
      [Security](https://docs.metronome.com/developer-resources/security/)
      endpoints allow you to retrieve security-related data.
  - name: Settings
    description: >-
      Use these endpoints to configure a billing API key, a webhook secret, or
      invoice finalization behavior.
  - name: Named schedules
    description: >-
      Named schedules are used for storing custom data that can change over
      time. Named schedules are often used in custom pricing logic.
paths:
  /v1/customer-alerts/list:
    post:
      tags:
        - Alerts
      summary: Get all threshold notifications
      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.


        ### 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
      operationId: listCustomerAlerts-v1
      parameters:
        - $ref: '#/components/parameters/NextPage'
      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
components:
  parameters:
    NextPage:
      name: next_page
      in: query
      description: Cursor that indicates where the next page of results should start.
      required: false
      schema:
        type: string
  schemas:
    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.
    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'
    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:
          $ref: '#/components/schemas/GroupKeyFilterType'
          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
        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.
    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
    CustomFieldFilterType:
      type: object
      required:
        - entity
        - key
        - value
      properties:
        entity:
          type: string
          enum:
            - Contract
            - Commit
            - ContractCredit
            - ContractCreditOrCommit
          x-mint-enum:
            ContractCreditOrCommit:
              - ff:alert-specifiers-enabled
        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'
    GroupValueFilterType:
      type: object
      required:
        - key
      properties:
        key:
          type: string
        value:
          type: string
    InvoiceType:
      type: string
      example: SCHEDULED or USAGE
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````