CloudConsole

aws cloudwatch set-alarm-state

Updated 16 November 2026 · How we write and check guides

Short answer

aws cloudwatch set-alarm-state --alarm-name my-alarm --state-value ALARM --state-reason "testing" forces an alarm into a state and runs that state's actions, which makes it the standard way to test notifications. The change is temporary: at the next evaluation the alarm returns to whatever its metric says.

Terminal running aws cloudwatch set-alarm-state --alarm-name prod-api-5x…
A worked example from this page. Copy commands from the text below, not from the image.

What the command does

The command overrides an alarm's state for a moment. If the new state differs from the current one, CloudWatch records a state change and runs the actions configured for the new state, exactly as a real breach would. Metric alarms then return to their real state very quickly, often within seconds, when CloudWatch next evaluates the metric; the forced state may only be visible in the alarm's history.

It works on metric alarms and composite alarms.

Syntax

aws cloudwatch set-alarm-state \
  --alarm-name <name> \
  --state-value OK|ALARM|INSUFFICIENT_DATA \
  --state-reason "text shown in history and notifications" \
  [--state-reason-data '{"json": "for machines"}']

The command prints nothing on success.

Worked examples

Test that a new alarm pages the right people:

aws cloudwatch set-alarm-state --alarm-name prod-api-5xx \
  --state-value ALARM --state-reason "Notification test by Jane - please ignore"

Then check delivery from the alarm's side:

aws cloudwatch describe-alarm-history --alarm-name prod-api-5xx \
  --history-item-type Action --max-records 5 \
  --query "AlarmHistoryItems[].[Timestamp,HistorySummary]" --output text

A summary like Failed to execute action points at the SNS topic policy or a missing subscription.

"Reset" an alarm after fixing the cause, so dashboards stop showing red before the next evaluation:

aws cloudwatch set-alarm-state --alarm-name prod-api-5xx \
  --state-value OK --state-reason "Manually reset after fix; metric will confirm"

Exercise an Auto Scaling or EC2 action in a test environment:

aws cloudwatch set-alarm-state --alarm-name staging-scale-out \
  --state-value ALARM --state-reason "Scale-out drill"

What happens next

SituationResult
Set to ALARM while metric is healthyActions fire, then the alarm returns to OK at the next evaluation and OK actions fire.
Set to OK while metric still breachesBriefly OK, then back to ALARM, firing alarm actions again.
Set to the state it is already inNo transition, so no actions run.
Actions disabled on the alarmState changes, but nothing is notified.

Gotchas

  • Warn people first. A test on a production alarm pages whoever is on call and may trigger automation such as scaling or instance recovery.
  • Setting OK is not muting. If the problem persists, the alarm fires again almost immediately. To silence it, use disable-alarm-actions or an actions suppressor on a composite alarm.
  • Write a clear reason. It appears in notifications and history; "test" alone confuses the next person reading the timeline.
  • Permissions. Restrict cloudwatch:SetAlarmState; it can trigger any action wired to an alarm.
  • Testing composite alarms. A composite alarm reacts to its children's state, so forcing a child into ALARM is a practical way to check the composite rule and its notifications end to end.
  • Look in history, not the console view. Because the forced state is overwritten so quickly, describe-alarm-history is the reliable place to confirm the test happened.

Questions

How do I test a CloudWatch alarm notification?

Run set-alarm-state with --state-value ALARM and a clear --state-reason. The alarm actions run as if the threshold had been breached.

How do I reset a CloudWatch alarm?

Use set-alarm-state --state-value OK. If the metric still breaches, the alarm goes straight back to ALARM at the next evaluation.

Will set-alarm-state keep the alarm in that state?

No. A metric alarm goes back to the state its data supports at the next evaluation, often within seconds.

When this happens away from your desk

Testing that an alarm actually reaches your phone is worth doing before you rely on it. CloudConsole, a phone app for AWS, is built to show alarm state changes and their history on a phone.

About the app → · Download on the App Store

Sources