Menu
Amazon CloudWatch
API Reference (API Version 2010-08-01)

GetMetricStatistics

Gets statistics for the specified metric.

The maximum number of data points that can be queried is 50,850, whereas the maximum number of data points returned from a single GetMetricStatistics request is 1,440. If you make a request that generates more than 1,440 data points, Amazon CloudWatch returns an error. In such a case, you can alter the request by narrowing the specified time range or increasing the specified period. A period can be as short as one minute (60 seconds) or as long as one day (86,400 seconds). Alternatively, you can make multiple requests across adjacent time ranges. GetMetricStatistics does not return the data in chronological order.

Amazon CloudWatch aggregates data points based on the length of the period that you specify. For example, if you request statistics with a one-minute granularity, Amazon CloudWatch aggregates data points with time stamps that fall within the same one-minute period. In such a case, the data points queried can greatly outnumber the data points returned.

The following examples show various statistics allowed by the data point query maximum of 50,850 when you call GetMetricStatistics on Amazon EC2 instances with detailed (one-minute) monitoring enabled:

  • Statistics for up to 400 instances for a span of one hour

  • Statistics for up to 35 instances over a span of 24 hours

  • Statistics for up to 2 instances over a span of 2 weeks

For information about the namespace, metric names, and dimensions that other Amazon Web Services products use to send metrics to CloudWatch, go to Amazon CloudWatch Metrics, Namespaces, and Dimensions Reference in the Amazon CloudWatch Developer Guide.

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

Dimensions.member.N

A list of dimensions describing qualities of the metric.

Type: array of Dimension objects

Array Members: Maximum number of 10 items.

Required: No

EndTime

The time stamp to use for determining the last datapoint to return. The value specified is exclusive; results will include datapoints up to the time stamp specified. The time stamp must be in ISO 8601 UTC format (e.g., 2014-09-03T23:00:00Z).

Type: Timestamp

Required: Yes

MetricName

The name of the metric, with or without spaces.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 255.

Required: Yes

Namespace

The namespace of the metric, with or without spaces.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 255.

Pattern: [^:].*

Required: Yes

Period

The granularity, in seconds, of the returned datapoints. A Period can be as short as one minute (60 seconds) or as long as one day (86,400 seconds), and must be a multiple of 60. The default value is 60.

Type: Integer

Valid Range: Minimum value of 60.

Required: Yes

StartTime

The time stamp to use for determining the first datapoint to return. The value specified is inclusive; results include datapoints with the time stamp specified. The time stamp must be in ISO 8601 UTC format (e.g., 2014-09-03T23:00:00Z).

Note

The specified start time is rounded down to the nearest value. Datapoints are returned for start times up to two weeks in the past. Specified start times that are more than two weeks in the past will not return datapoints for metrics that are older than two weeks.

Data that is timestamped 24 hours or more in the past may take in excess of 48 hours to become available from submission time using GetMetricStatistics.

Type: Timestamp

Required: Yes

Statistics.member.N

The metric statistics to return. For information about specific statistics returned by GetMetricStatistics, see Statistics in the Amazon CloudWatch Developer Guide.

Type: array of Strings

Array Members: Minimum number of 1 item. Maximum number of 5 items.

Valid Values: SampleCount | Average | Sum | Minimum | Maximum

Required: Yes

Unit

The specific unit for a given metric. Metrics may be reported in multiple units. Not supplying a unit results in all units being returned. If the metric only ever reports one unit, specifying a unit will have no effect.

Type: String

Valid Values: Seconds | Microseconds | Milliseconds | Bytes | Kilobytes | Megabytes | Gigabytes | Terabytes | Bits | Kilobits | Megabits | Gigabits | Terabits | Percent | Count | Bytes/Second | Kilobytes/Second | Megabytes/Second | Gigabytes/Second | Terabytes/Second | Bits/Second | Kilobits/Second | Megabits/Second | Gigabits/Second | Terabits/Second | Count/Second | None

Required: No

Response Elements

The following elements are returned by the service.

Datapoints.member.N

The datapoints for the specified metric.

Type: array of Datapoint objects

Label

A label describing the specified metric.

Type: String

Errors

For information about the errors that are common to all actions, see Common Errors.

InternalServiceError

Indicates that the request processing has failed due to some unknown error, exception, or failure.

HTTP Status Code: 500

InvalidParameterCombination

Parameters that must not be used together were used together.

HTTP Status Code: 400

InvalidParameterValue

Bad or out-of-range value was supplied for the input parameter.

HTTP Status Code: 400

MissingParameter

An input parameter that is mandatory for processing the request is not supplied.

HTTP Status Code: 400