Amazon Elastic Compute Cloud
API Reference (API Version 2016-11-15)

Monitoring API Requests with Amazon CloudWatch


This is an opt-in feature. To enable this feature for your AWS account, contact AWS Support.

You can monitor Amazon EC2 API requests using Amazon CloudWatch, which collects raw data and processes it into readable, near real-time metrics. These metrics provide a simple way to track the usage and outcomes of the Amazon EC2 API operations over time. This information gives you a better perspective on how your web applications are performing, and enables you to identify and diagnose a variety of issues. You can also set alarms that watch for certain thresholds, and send notifications or take specific actions when those thresholds are met.

For more information about CloudWatch, see the Amazon CloudWatch User Guide.

Amazon EC2 API Metrics and Dimensions


The Amazon EC2 API metrics are contained in the AWS/EC2/API namespace. The following tables list the metrics available for Amazon EC2 API requests.

Metric Description


The number of failed API requests caused by client errors.

These errors are usually caused by something the client did, such as specifying an incorrect or invalid parameter in the request, or using an action or resource on behalf of a user that does not have permission to use the action or resource.

Unit: Count


The number of times the maximum request rate permitted by the Amazon EC2 APIs has been exceeded for your account.

Amazon EC2 API requests are throttled to help maintain the performance of the service. If your requests have been throttled, you get the Client.RequestLimitExceeded error.

Unit: Count


The number of failed API requests caused by internal server errors.

These errors are usually caused by an AWS server-side error, exception, or failure.

Unit: Count


The number of successful API requests.

Unit: Count

For more information about metrics, see Amazon CloudWatch Concepts.


The Amazon EC2 metric data can be filtered across all EC2 API actions. For more information about dimensions, see Amazon CloudWatch Concepts.

Metric Data Retention

Amazon EC2 API metrics are sent to CloudWatch at 1-minute intervals. CloudWatch retains metric data as follows:

  • Data points with a period of 60 seconds (1 minute) are available for 15 days.

  • Data points with a period of 300 seconds (5 minutes) are available for 63 days.

  • Data points with a period of 3600 seconds (1 hour) are available for 455 days (15 months).


Standard CloudWatch pricing and charges apply. No additional charges are applied for using the Amazon EC2 API metrics. For more information, see Amazon CloudWatch Pricing.

Working with Amazon CloudWatch

Viewing CloudWatch Metrics

You can view Amazon EC2 API metrics using the CloudWatch console and the command line tools.

To view metrics using the CloudWatch console

  1. Open the CloudWatch console at

  2. In the navigation pane, choose Metrics.

  3. Under All metrics, choose the AWS/EC2/API metric namespace.

  4. To view the metrics, select the metric dimension.

To view metrics using the command line tools

Use one of the following commands:

  • list-metrics (AWS CLI)

    aws cloudwatch list-metrics --namespace "AWS/EC2/API"
  • Get-CWMetricList (AWS Tools for Windows PowerShell)

    Get-CWMetricList -Namespace "AWS/EC2/API"

Creating CloudWatch Alarms

You can create a CloudWatch alarm that sends an Amazon SNS message when the alarm changes state. An alarm watches a single metric over a time period that you specify. It sends a notification to an SNS topic based on the value of the metric relative to a given threshold over a number of time periods.

For example, you can create an alarm that monitors the number of DescribeInstances API requests that fail due to server-side errors. The following alarm sends an email notification when the number of DescribeInstances API request failures reach a threshold of 10 server-side errors during a 5-minute period.

To create an alarm for Amazon EC2 DescribeInstances API request server errors

  1. Open the CloudWatch console at

  2. In the navigation pane, choose Alarms, Create Alarm.

  3. Choose EC2/API Metrics.

  4. Select the DescribeInstances API operation and the ServerErrors metric and choose Next.

  5. Configure the alarm as follows, and choose Create Alarm when you are done:

    1. Under Alarm Threshold, enter a name and description for your alarm.

    2. For Whenever, choose >=, enter 10, and then enter 1 for the consecutive periods.

    3. Under Actions, select an existing notification list or choose New list.

    4. Under Alarm Preview, select a period of 5 minutes and specify a statistic of Sum.

For more information, see Creating Amazon CloudWatch Alarms in the Amazon CloudWatch User Guide.