# Alert statuses

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


An alert status represents the runtime evaluation of an [alert](/docs/api/alerts) for a specific [subscription](/docs/api/subscriptions). While the [alert](/docs/api/alerts/alert-object) resource defines the threshold rule, the alert status tells you whether a subscription is currently `within_limit` or `in_alarm` for that rule. Statuses are tracked for every alert type — `usage_exceeded`, `spend_exceeded`, and `credit_balance_dropped`.

Each alert status tracks:

-   `alarm_status`: The current state — `within_limit` (the subscription is within the configured threshold) or `in_alarm` (the threshold has been breached).
-   `alarm_triggered_at`: The timestamp when the alert last entered the `in_alarm` state. This is `null` if the alert has never been triggered for this subscription.

**Note:** Alert statuses are computed by Chargebee based on billing data and the alert configuration. They are read-only — you cannot create or update an alert status directly. To change the threshold rule, use the [Alerts](/docs/api/alerts) API.

## Sample Alert status

```json
{
  "alert_status": {
    "alert_id": "alert___dev__3Nl7purV3LwbKYH",
    "subscription_id": "sub_KyV2S7Qm8tL7p",
    "alarm_status": "in_alarm",
    "alarm_triggered_at": 1763885000,
    "object": "alert_status",
    "resource_version": 1763885000000
  }
}
```

## Alert statuses attributes

## Input Parameters

- `alert_id` (required, string, max chars=50)
  The identifier of the [alert](/docs/api/alerts) configuration that this status corresponds to.

- `subscription_id` (required, string, max chars=50)
  The identifier of the [subscription](/docs/api/subscriptions) that this status is evaluated for.

- `alarm_status` (required, enumerated string)
  The current runtime state of the alert for this subscription. Indicates whether the subscription is within the configured threshold or has breached it.
  Possible enum values:
    - `within_limit`
      The subscription is within the configured threshold.
    - `in_alarm`
      The configured threshold has been breached and the alert has been triggered for this subscription. Depending on the alert `type`, this means the measured value has reached or exceeded the threshold (`usage_exceeded`, `spend_exceeded`) or the credit balance has dropped to or below it (`credit_balance_dropped`).

- `alarm_triggered_at` (optional, timestamp(UTC) in seconds)
  Timestamp (UTC, in seconds) indicating when the alert last entered the `in_alarm` state for this subscription. `null` if the alert has never been triggered.