CloudConsole

aws cloudwatch describe-alarms

Updated 16 November 2026 · How we write and check guides

Short answer

aws cloudwatch describe-alarms --state-value ALARM --query "MetricAlarms[].[AlarmName,StateReason]" --output table shows every metric alarm currently firing in the region. Filter by name with --alarm-name-prefix, add --alarm-types CompositeAlarm MetricAlarm to include composite alarms, and use --action-prefix to find alarms that notify a given SNS topic.

Terminal running aws cloudwatch describe-alarms --state-value ALARM \
A worked example from this page. Copy commands from the text below, not from the image.

What the command does

The response has two lists: MetricAlarms[] and CompositeAlarms[]. Metric alarm entries include AlarmName, StateValue (OK, ALARM or INSUFFICIENT_DATA), StateReason, StateUpdatedTimestamp, ActionsEnabled, the alarm and OK actions, and the full definition: namespace, metric, dimensions, statistic, period, evaluation periods, threshold and comparison operator.

If you do not pass --alarm-types, only metric alarms are returned, even when composite alarms exist.

Syntax

aws cloudwatch describe-alarms \
  [--alarm-names a b | --alarm-name-prefix prod-] \
  [--state-value OK|ALARM|INSUFFICIENT_DATA] \
  [--alarm-types MetricAlarm CompositeAlarm] \
  [--action-prefix arn:aws:sns:eu-west-2:123456789012:oncall]

Worked examples

What is firing right now:

aws cloudwatch describe-alarms --state-value ALARM \
  --query "MetricAlarms[].[AlarmName,StateUpdatedTimestamp,StateReason]" --output table

Including composite alarms:

aws cloudwatch describe-alarms --state-value ALARM --alarm-types MetricAlarm CompositeAlarm \
  --query "[MetricAlarms[].AlarmName, CompositeAlarms[].AlarmName][]" --output text

Alarms with notifications switched off, often forgotten after maintenance:

aws cloudwatch describe-alarms \
  --query "MetricAlarms[?ActionsEnabled==\`false\`].AlarmName" --output text

Alarms that would page a particular SNS topic:

aws cloudwatch describe-alarms --action-prefix arn:aws:sns:eu-west-2:123456789012:oncall \
  --query "MetricAlarms[].AlarmName" --output text

Alarms with no actions at all, which alert nobody:

aws cloudwatch describe-alarms \
  --query "MetricAlarms[?length(AlarmActions)==\`0\`].AlarmName" --output text

The full definition of one alarm, ready to recreate or compare:

aws cloudwatch describe-alarms --alarm-names prod-api-5xx \
  --query "MetricAlarms[0].{ns:Namespace,metric:MetricName,dims:Dimensions,stat:Statistic,period:Period,eval:EvaluationPeriods,dta:DatapointsToAlarm,thr:Threshold,op:ComparisonOperator,missing:TreatMissingData}"

Which alarms watch this resource?

During an incident you often start from a resource rather than an alarm name. describe-alarms-for-metric answers "what alarms exist on this metric?", given the same namespace, metric name and dimensions the alarm uses:

aws cloudwatch describe-alarms-for-metric \
  --namespace AWS/EC2 --metric-name CPUUtilization \
  --dimensions Name=InstanceId,Value=i-0123456789abcdef0 \
  --query "MetricAlarms[].[AlarmName,StateValue,Threshold]" --output table

For a broader sweep, search the alarm definitions themselves, for example every alarm that mentions a given Lambda function in its dimensions:

aws cloudwatch describe-alarms \
  --query "MetricAlarms[?Dimensions[?Value=='checkout']].[AlarmName,MetricName,StateValue]" --output table

Alarms built with metric math keep their metrics under Metrics[] rather than the top-level fields, so they do not show up in either query; look for them by name prefix instead.

Reading alarm state

StateMeans
OKThe metric is within the threshold.
ALARMEnough datapoints breached; StateReason lists the values that did.
INSUFFICIENT_DATANot enough data to evaluate: new alarm, metric stopped reporting, or dimensions that match no metric at all.

An alarm stuck in INSUFFICIENT_DATA forever usually has a typo in a dimension name or value. Compare with aws cloudwatch list-metrics.

Gotchas

  • Per region. Alarms live in the region of their metric; billing alarms live in us-east-1.
  • Text output and pagination. Accounts with many alarms span several pages; projections work fine, but use JSON output if you sort or count.
  • Prefix filters are case-sensitive and only match the start of the name, so a consistent naming scheme (prod-service-signal) pays off.
  • History is separate. This shows the current state only; use describe-alarm-history to see when it changed.

Questions

How do I list all CloudWatch alarms with the CLI?

aws cloudwatch describe-alarms --query "MetricAlarms[].[AlarmName,StateValue]" --output table, plus --alarm-types CompositeAlarm if you use composite alarms.

How do I list only alarms in ALARM state?

Pass --state-value ALARM to describe-alarms.

How do I see the history of an alarm?

Use aws cloudwatch describe-alarm-history --alarm-name <name> --history-item-type StateUpdate.

When this happens away from your desk

The list of alarms currently firing is the first screen most people want when paged. CloudConsole, a phone app for AWS, is built to show exactly that on a phone, with the metric and logs behind each alarm.

About the app → · Download on the App Store

Sources