subscriptions

List subscription alerts

Changed on Nov 5, 2026

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

get/subscriptions/{external_id}/alerts

Request

Base URL
https://api.getlago.com/api/v1
Auth
HTTP bearer
TypeScript
https://skmtc.dev/getlago/apis/lago-api-documentation/docs/subscriptions/:external_id/alerts/get.ts
A function with typed inputs. Its response is checked against the schema.

Query parameters

subscription_status'pending' | 'active' | 'terminated' | 'canceled' | 'incomplete'

Example:active

Filter by subscription status. When provided, the subscription is looked up with this status instead of the default active status. Possible values are pending, active, terminated, canceled, or incomplete.

pageinteger

Example:1

Page number. Defaults to 1. A value that is not a positive integer, such as 0, returns the first page.

per_pageinteger

Example:20

Number of records per page. Defaults to 100. The maximum is 200, unless another maximum is configured for your organization. A value above the maximum returns a 422 error with value_is_out_of_range on per_page. A value that is not a positive integer, such as 0, returns the default number of records.

Response

Subscription alerts

Example response

{
  "alerts": [
    {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "lago_organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "external_subscription_id": "sub_1234567890",
      "billable_metric": {
        "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
        "name": "Storage",
        "code": "storage",
        "description": "GB of storage used in my application",
        "rounding_function": "round",
        "rounding_precision": 2,
        "created_at": "2022-09-14T16:35:31Z",
        "expression": "round((event.properties.ended_at - event.properties.started_at) * event.properties.units)",
        "field_name": "gb",
        "aggregation_type": "sum_agg",
        "weighted_interval": "seconds",
        "filters": [
          {
            "key": "region",
            "values": [
              "us-east-1"
            ]
          }
        ]
      },
      "alert_type": "billable_metric_current_usage_amount",
      "code": "storage_threshold_alert",
      "name": "Storage Usage Alert",
      "direction": "increasing",
      "previous_value": "1000.0",
      "last_processed_at": "2025-05-19T10:04:21Z",
      "thresholds": [
        {
          "code": "warn",
          "notify_on": [
            "triggered",
            "resolved"
          ],
          "value": "99.0"
        }
      ],
      "created_at": "2025-03-20T10:00:00Z"
    }
  ],
  "meta": {
    "current_page": 2,
    "next_page": 3,
    "prev_page": 1,
    "total_pages": 4,
    "total_count": 70
  }
}

Changes

Nov 5, 2026b216574b9612 Revision changes
- info
  the response property /////// became required for the status
- info
  the response property /////// became required for the status
- info
  the response property /////// became required for the status
- info
  the response property /////// became required for the status
- info
  the response property /////// became required for the status
- info
  the response property /////// became required for the status
Nov 3, 20265d26657495a3 Revision changes
- breaking
  added subschema #2 to the // response property oneOf list for the response status
- breaking
  the // response's property type changed from object to no type for status
- breaking
  the // response's property type changed from number to string for status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- breaking
  removed the required property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  removed the optional property /// from the response with the status
- warning
  added the new billable_metric_lifetime_usage_units enum value to the // response property for the response status
- info
  added the new optional query request parameter page
- info
  added the new optional query request parameter per_page
- info
  added the new enum value incomplete to the query request parameter subscription_status
- info
  added the optional property //////// to the response with the status
- info
  the response property // became required for the status
- info
  the response property // became required for the status
- info
  the response property // became required for the status
- info
  the ///// response's property pattern was changed from ^[0-9]+.?[0-9]*$ to ^-?[0-9]+(\.[0-9]+)?$ for the status

Operation history