CloudConsole

aws cloudwatch get-metric-data

Updated 16 November 2026 · How we write and check guides

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.

Terminal running aws cloudwatch get-metric-data --metric-data-queries… with its example output
A worked example from this page with its output. Copy commands from the text below, not from the image.

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-dataget-metric-statistics
Metrics per callUp to 500 queriesOne
Metric math and SEARCHYesNo
Large rangesPaginates with NextToken1,440 datapoints maximum
Output orderSorted (newest first by default)Unsorted
Output shapeParallel arrays per queryList 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 app → · Download on the App Store

Sources