# aws cloudwatch get-metric-statistics

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws cloudwatch get-metric-statistics --namespace AWS/EC2 --metric-name CPUUtilization --dimensions Name=InstanceId,Value=i-0123456789abcdef0 --start-time 2026-11-16T00:00:00Z --end-time 2026-11-16T06:00:00Z --period 300 --statistics Average Maximum returns one metric's values over a time range. Datapoints come back unsorted, so sort them in --query, and a call can return at most 1,440 datapoints.

## What the command does

This is the simplest way to read a single metric. You name the metric with its namespace, metric name and exact dimensions, pick a time range, a period and one or more statistics (or percentiles with `--extended-statistics`), and get back `Datapoints[]`, each with a `Timestamp`, the requested statistics and a `Unit`.

For several metrics at once, metric math, or more than 1,440 points, use `get-metric-data` instead.

## Syntax

```
aws cloudwatch get-metric-statistics \
  --namespace AWS/EC2 --metric-name CPUUtilization \
  --dimensions Name=InstanceId,Value=i-0123456789abcdef0 \
  --start-time 2026-11-16T00:00:00Z --end-time 2026-11-16T06:00:00Z \
  --period 300 \
  --statistics Average Maximum   (or --extended-statistics p99)
```

## Worked examples

**EC2 CPU for the last three hours, in time order** (GNU `date`):

```
aws cloudwatch get-metric-statistics \
  --namespace AWS/EC2 --metric-name CPUUtilization \
  --dimensions Name=InstanceId,Value=i-0123456789abcdef0 \
  --start-time $(date -u -d '3 hours ago' +%FT%TZ) --end-time $(date -u +%FT%TZ) \
  --period 300 --statistics Average Maximum \
  --query "sort_by(Datapoints,&Timestamp)[].[Timestamp,Average,Maximum]" --output table
```

**Lambda p99 duration per hour over a day**:

```
aws cloudwatch get-metric-statistics \
  --namespace AWS/Lambda --metric-name Duration \
  --dimensions Name=FunctionName,Value=checkout \
  --start-time $(date -u -d '1 day ago' +%FT%TZ) --end-time $(date -u +%FT%TZ) \
  --period 3600 --extended-statistics p99 \
  --query "sort_by(Datapoints,&Timestamp)[].[Timestamp,ExtendedStatistics.p99]" --output text
```

**Total requests to a load balancer yesterday** as a single number:

```
aws cloudwatch get-metric-statistics \
  --namespace AWS/ApplicationELB --metric-name RequestCount \
  --dimensions Name=LoadBalancer,Value=app/prod-alb/0123456789abcdef \
  --start-time 2026-11-15T00:00:00Z --end-time 2026-11-16T00:00:00Z \
  --period 86400 --statistics Sum --query "Datapoints[0].Sum"
```

**S3 bucket size** (a daily storage metric, so use a day-long period):

```
aws cloudwatch get-metric-statistics --namespace AWS/S3 --metric-name BucketSizeBytes \
  --dimensions Name=BucketName,Value=my-bucket Name=StorageType,Value=StandardStorage \
  --start-time $(date -u -d '2 days ago' +%FT%TZ) --end-time $(date -u +%FT%TZ) \
  --period 86400 --statistics Average
```

## Retention and period rules

| Data age | Smallest period available |
|---|---|
| Up to 3 hours (high-resolution metrics) | 1 second |
| Up to 15 days | 60 seconds |
| 15 to 63 days | 5 minutes |
| 63 to 455 days | 1 hour |

Asking for a finer period than the data's age allows returns empty or partial results.

## Gotchas

- **Datapoints are not sorted.** Always use `sort_by(Datapoints,&Timestamp)`.
- **1,440 datapoint limit.** Range divided by period must not exceed it; raise the period or split the range.
- **All dimensions, exactly.** If the metric is published with two dimensions, passing one returns nothing. Check combinations with `list-metrics`.
- **Empty means no data, not zero.** Many AWS metrics, such as Lambda `Errors`, are only published when there is activity.
- **Times are UTC.** Use the `Z` suffix or an explicit offset to avoid off-by-hours surprises.

## Questions

### What is the difference between get-metric-statistics and get-metric-data?

get-metric-statistics reads one metric with simple statistics. get-metric-data reads up to hundreds of metrics per call, supports metric math and search expressions, and paginates large results.

### Why does get-metric-statistics return no datapoints?

Usually the dimensions do not match exactly, the time range has no activity, or the period is finer than the data's retention allows.

### How do I get CloudWatch log events instead of metrics?

Logs are a separate service: use aws logs filter-log-events or aws logs tail.

## When this happens away from your desk

A quick look at a metric's recent shape often tells you whether an alarm is real. CloudConsole, a phone app for AWS, is built to show the metric behind each alarm on a phone.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [AWS CLI Command Reference: cloudwatch get-metric-statistics](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-statistics.html)
- [GetMetricStatistics API reference](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricStatistics.html)
- [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)

## Related

- [aws cloudwatch get-metric-data](https://cloudconsole.dev/cli/cloudwatch-get-metric-data)
- [aws cloudwatch list-metrics](https://cloudconsole.dev/cli/cloudwatch-list-metrics)
- [aws cloudwatch put-metric-alarm](https://cloudconsole.dev/cli/cloudwatch-put-metric-alarm)
- [CloudWatch alarm for EC2 CPUUtilization](https://cloudconsole.dev/alarms/ec2-cpuutilization)
- [CloudWatch alarm: Lambda Duration (p90)](https://cloudconsole.dev/alarms/lambda-duration)
- [aws cloudwatch describe-alarm-history](https://cloudconsole.dev/cli/cloudwatch-describe-alarm-history)

---

Source: https://cloudconsole.dev/cli/cloudwatch-get-metric-statistics

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
