DescribeAlarmHistoryCommand

Suggest an Edit

Retrieves the history for the specified alarm. You can filter the results by date range or item type. If an alarm name is not specified, the histories for either all metric alarms or all composite alarms are returned.

CloudWatch retains the history of an alarm even if you delete the alarm.

To use this operation and return information about a composite alarm, you must be signed on with the cloudwatch:DescribeAlarmHistory permission that is scoped to *. You can't return information about composite alarms if your cloudwatch:DescribeAlarmHistory permission has a narrower scope.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { CloudWatchClient, DescribeAlarmHistoryCommand } from "@aws-sdk/client-cloudwatch"; // ES Modules import
// const { CloudWatchClient, DescribeAlarmHistoryCommand } = require("@aws-sdk/client-cloudwatch"); // CommonJS import
const client = new CloudWatchClient(config);
const input = { // DescribeAlarmHistoryInput
  AlarmName: "STRING_VALUE",
  AlarmTypes: [ // AlarmTypes
    "CompositeAlarm" || "MetricAlarm",
  ],
  HistoryItemType: "ConfigurationUpdate" || "StateUpdate" || "Action",
  StartDate: new Date("TIMESTAMP"),
  EndDate: new Date("TIMESTAMP"),
  MaxRecords: Number("int"),
  NextToken: "STRING_VALUE",
  ScanBy: "TimestampDescending" || "TimestampAscending",
};
const command = new DescribeAlarmHistoryCommand(input);
const response = await client.send(command);
// { // DescribeAlarmHistoryOutput
//   AlarmHistoryItems: [ // AlarmHistoryItems
//     { // AlarmHistoryItem
//       AlarmName: "STRING_VALUE",
//       AlarmType: "CompositeAlarm" || "MetricAlarm",
//       Timestamp: new Date("TIMESTAMP"),
//       HistoryItemType: "ConfigurationUpdate" || "StateUpdate" || "Action",
//       HistorySummary: "STRING_VALUE",
//       HistoryData: "STRING_VALUE",
//     },
//   ],
//   NextToken: "STRING_VALUE",
// };

DescribeAlarmHistoryCommand Input

See DescribeAlarmHistoryCommandInput for more details

Parameter
Type
Description
AlarmName
string | undefined

The name of the alarm.

AlarmTypes
AlarmType[] | undefined

Use this parameter to specify whether you want the operation to return metric alarms or composite alarms. If you omit this parameter, only metric alarms are returned.

EndDate
Date | undefined

The ending date to retrieve alarm history.

HistoryItemType
HistoryItemType | undefined

The type of alarm histories to retrieve.

MaxRecords
number | undefined

The maximum number of alarm history records to retrieve.

NextToken
string | undefined

The token returned by a previous call to indicate that there is more data available.

ScanBy
ScanBy | undefined

Specified whether to return the newest or oldest alarm history first. Specify TimestampDescending to have the newest event history returned first, and specify TimestampAscending to have the oldest history returned first.

StartDate
Date | undefined

The starting date to retrieve alarm history.

DescribeAlarmHistoryCommand Output

See DescribeAlarmHistoryCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
AlarmHistoryItems
AlarmHistoryItem[] | undefined

The alarm histories, in JSON format.

NextToken
string | undefined

The token that marks the start of the next batch of returned results.

Throws

Name
Fault
Details
InvalidNextToken
client

The next token specified is invalid.

CloudWatchServiceException
Base exception class for all service exceptions from CloudWatch service.