---
title: "List subscription alerts"
method: GET
path: "/subscriptions/{external_id}/alerts"
tags: ["subscriptions"]
---

# List subscription alerts

`GET /subscriptions/{external_id}/alerts`

This endpoint enables the retrieval of all alerts for a subscription.

## Query parameters

- `subscription_status` 'pending' | 'active' | 'terminated' | 'canceled'

## Response `200`

Subscription alerts

- Alerts
  - `alerts` AlertObject[], required
    - `lago_id` string, uuid, required — Unique identifier of the alert, created by Lago.
    - `lago_organization_id` string, uuid, required — Unique identifier of the organization, created by Lago.
    - `external_subscription_id` string, nullable, required — The subscription external unique identifier (provided by your own application).
    - `lago_wallet_id` unknown
    - `wallet_code` unknown
    - `billable_metric` BillableMetricObject, required
      - `lago_id` string, uuid, required — Unique identifier of the billable metric created by Lago.
      - `name` string, required — Name of the billable metric.
      - `code` string, required — Unique code used to identify the billable metric associated with the API request. This code associates each event with the correct metric.
      - `description` string, nullable — Internal description of the billable metric.
      - `recurring` boolean, required — Defines if the billable metric is persisted billing period over billing period. - If set to `true`: the accumulated number of units calculated from the previous billing period is persisted to the next billing period. - If set to `false`: the accumulated number of units is reset to 0 at the end of the billing period. - If not defined in the request, default value is `false`.
      - `rounding_function` 'ceil' | 'floor' | 'round' | 'null', nullable — Refers to the numeric value or mathematical expression that will be rounded based on the calculated number of billing units. Possible values are `round`, `ceil` and `floor`.
      - `rounding_precision` integer, nullable — Specifies the number of decimal places to which the `rounding_function` will be rounded. It can be a positive or negative value.
      - `created_at` string, date-time, required — Creation date of the billable metric.
      - `expression` string — Expression used to calculate the event units. The expression is evalutated for each event and the result is then used to calculate the total aggregated units.
      - `field_name` string, nullable — Property of the billable metric used for aggregating usage data. This field is not required for `count_agg`.
      - `aggregation_type` 'count_agg' | 'sum_agg' | 'max_agg' | 'unique_count_agg' | 'weighted_sum_agg' | 'latest_agg', required — Aggregation method used to compute usage for this billable metric.
      - `weighted_interval` 'seconds' | 'null', nullable — Parameter exclusively utilized in conjunction with the `weighted_sum` aggregation type. It serves to adjust the aggregation result by assigning weights and proration to the result based on time intervals. When this field is not provided, the default time interval is assumed to be in `seconds`.
      - `filters` BillableMetricFilterObject[]
        - `key` string, required — Filter key to add to the event properties payload
        - `values` string[], required — List of possible filter values
    - `alert_type` 'current_usage_amount' | 'billable_metric_current_usage_amount' | 'billable_metric_current_usage_units' | 'lifetime_usage_amount', required — The type of alert.
    - `code` string, required — Unique code used to identify the alert.
    - `name` string, nullable, required — The name of the alert.
    - `direction` 'increasing' | 'decreasing' — Indicates whether the alert is triggered when the monitored metric goes above or below the threshold.
    - `previous_value` number, required — When the system checked if this alert should be triggered, this value was retrieved and checked against the thresholds.
    - `last_processed_at` string, date-time, nullable, required — The date and time in UTC (ISO 8601) when the system checked if this alert should be triggered. Null until it's processed for the first time.
    - `thresholds` AlertThresholdObject[], required — Array of thresholds associated with the alert.
      - `code` string, nullable, required — Unique identifier of the usage threshold created by Lago.
      - `recurring` boolean, required — This field when set to `true` indicates that the alert will be retrigger when this threshold is reached after the last non-recurring threshold. Only one recurring threshold per alert allowed.
      - `value` string, required — A value that should trigger this alert, formatted as a BigDecimal.
    - `created_at` string, date-time, required — The date and time in UTC (ISO 8601) when the alert was created.
  - `meta` PaginationMeta
    - `current_page` integer, required — Current page.
    - `next_page` integer, nullable — Next page.
    - `prev_page` integer, nullable — Previous page.
    - `total_pages` integer, required — Total number of pages.
    - `total_count` integer, required — Total number of records.

## Other responses

- `401` — Unauthorized error
- `404` — Not Found error

---

[API](https://skmtc.dev/getlago/apis/lago-api-documentation.md) · [All operations](https://skmtc.dev/getlago/apis/lago-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getlago/lago-api-documentation/revisions/6e969ef3bb45/schema)