# aws cloudwatch get-metric-data

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws cloudwatch get-metric-data --metric-data-queries file://queries.json --start-time ... --end-time ... retrieves several metrics in one call, and can compute metric math expressions such as error rates or run SEARCH expressions across many resources. Results come back as parallel Timestamps and Values arrays per query ID, newest first by default.

## What the command does

Each entry in `--metric-data-queries` is either a `MetricStat` (a metric with period and statistic) or an `Expression` (metric math, or a `SEARCH`). Queries have an `Id` so expressions can refer to them, and `ReturnData` controls whether a query appears in the output. The response has `MetricDataResults[]` with `Id`, `Label`, `Timestamps`, `Values` and a `StatusCode` of `Complete` or `PartialData`.

## Syntax

```
aws cloudwatch get-metric-data \
  --metric-data-queries file://queries.json \
  --start-time 2026-11-16T00:00:00Z --end-time 2026-11-16T06:00:00Z \
  [--scan-by TimestampAscending|TimestampDescending] \
  [--max-datapoints 1000]
```

## Worked examples

**Lambda error rate**, with only the computed series returned. `queries.json`:

```
[
  { "Id": "errors", "ReturnData": false,
    "MetricStat": { "Metric": { "Namespace": "AWS/Lambda", "MetricName": "Errors",
      "Dimensions": [{ "Name": "FunctionName", "Value": "checkout" }] }, "Period": 300, "Stat": "Sum" } },
  { "Id": "invocations", "ReturnData": false,
    "MetricStat": { "Metric": { "Namespace": "AWS/Lambda", "MetricName": "Invocations",
      "Dimensions": [{ "Name": "FunctionName", "Value": "checkout" }] }, "Period": 300, "Stat": "Sum" } },
  { "Id": "rate", "Expression": "IF(invocations > 0, 100 * errors / invocations, 0)", "Label": "Error %" }
]
```

```
aws cloudwatch get-metric-data --metric-data-queries file://queries.json \
  --start-time $(date -u -d '6 hours ago' +%FT%TZ) --end-time $(date -u +%FT%TZ) \
  --scan-by TimestampAscending \
  --query "MetricDataResults[0].[Timestamps,Values]" --output json
```

**CPU of every EC2 instance at once** with a search expression. Put it in `search.json`, because the nested quotes are painful to get right inline:

```
[
  { "Id": "cpu",
    "Expression": "SEARCH('{AWS/EC2,InstanceId} MetricName=\"CPUUtilization\"', 'Average', 300)" }
]
```

```
aws cloudwatch get-metric-data --metric-data-queries file://search.json \
  --start-time $(date -u -d '1 hour ago' +%FT%TZ) --end-time $(date -u +%FT%TZ) \
  --query "MetricDataResults[].[Label, max(Values)]" --output text
```

Each matching instance becomes its own result, labelled with its instance ID, so this prints the peak CPU of every instance in the last hour.

**Pair timestamps with values** for reading:

```
aws cloudwatch get-metric-data --metric-data-queries file://queries.json \
  --start-time 2026-11-16T00:00:00Z --end-time 2026-11-16T06:00:00Z --output json \
  | jq -r '.MetricDataResults[0] | [.Timestamps, .Values] | transpose[] | @tsv'
```

## Compared with get-metric-statistics

| | get-metric-data | get-metric-statistics |
|---|---|---|
| Metrics per call | Up to 500 queries | One |
| Metric math and SEARCH | Yes | No |
| Large ranges | Paginates with `NextToken` | 1,440 datapoints maximum |
| Output order | Sorted (newest first by default) | Unsorted |
| Output shape | Parallel arrays per query | List of datapoint objects |

## Gotchas

- **Ids must start with a lower-case letter** and may contain only letters, numbers and underscores.
- **`PartialData`** means there is more to fetch; the CLI follows `NextToken` for you, but scripts using the SDK must loop.
- **Newest first.** Pass `--scan-by TimestampAscending` for chronological arrays.
- **Billing.** Unlike many read APIs, this one is charged by the number of metrics requested, so dashboards or scripts polling hundreds of metrics every minute add up.
- **Empty results** for a `MetricStat` usually mean a dimension mismatch; check with `list-metrics`.

## Questions

### How do I use get-metric-data with metric math?

Define the input metrics with ReturnData false, then add a query with an Expression that refers to their Ids, such as 100 * errors / invocations.

### Why are get-metric-data results in reverse order?

The default ordering is TimestampDescending. Pass --scan-by TimestampAscending to get oldest first.

### Is get-metric-data more expensive than get-metric-statistics?

get-metric-data is billed per metric requested. For an occasional single-metric lookup either is fine; for bulk retrieval get-metric-data needs far fewer calls.

## When this happens away from your desk

Error rates rather than raw counts are usually what you want to see when deciding whether to act. CloudConsole, a phone app for AWS, is built to show metrics and alarms in a form that reads well 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-data](https://docs.aws.amazon.com/cli/latest/reference/cloudwatch/get-metric-data.html)
- [GetMetricData API reference](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_GetMetricData.html)
- [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html)

## Related

- [aws cloudwatch get-metric-statistics](https://cloudconsole.dev/cli/cloudwatch-get-metric-statistics)
- [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: Lambda Errors](https://cloudconsole.dev/alarms/lambda-errors)
- [Percentile latency with CloudWatch Logs Insights](https://cloudconsole.dev/logs-insights/percentile-latency)
- [aws cloudwatch describe-alarm-history](https://cloudconsole.dev/cli/cloudwatch-describe-alarm-history)

---

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

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