Request Syntax Request Parameters Response Syntax Response Elements Errors Examples See Also

GetMetricDataQueryDefinition

Returns a metric data query definition, including its expression.

Permissions

To get a definition, you need the cloudwatch:GetMetricDataQueryDefinition permission on the metric data query definition resource. You can use the aws:ResourceTag/${TagKey} condition key to control access based on the tags of the definition.

Request Syntax


{
   "Id": "string"
}

Request Parameters

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

The request accepts the following data in JSON format.

Id

The ID of the metric data query definition to retrieve.

Type: String

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

Pattern: [a-zA-Z0-9-]{1,64}

Required: Yes

Response Syntax


{
   "Arn": "string",
   "CreatedAt": number,
   "Expression": "string",
   "Id": "string",
   "Path": "string",
   "Type": "string",
   "UpdatedAt": number
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Arn

The Amazon Resource Name (ARN) of the metric data query definition.

Type: String

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

CreatedAt

The date and time when you created the metric data query definition.

Type: Timestamp

Expression

The query expression.

Type: String

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

Id

The ID of the metric data query definition.

Type: String

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

Pattern: [a-zA-Z0-9-]{1,64}

Path

The path of the metric data query definition.

Type: String

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

Pattern: [\p{L}\p{M}\p{N}\p{P}\p{S}\p{Zs}]+

Type

The language of the expression. Valid values are the following:

PROMQL – A PromQL query.
SQL – A CloudWatch Metrics Insights query.
METRIC_MATH – A metric math expression.

Type: String

Valid Values: PROMQL | SQL | METRIC_MATH

UpdatedAt

The date and time when you last updated the metric data query definition.

Type: Timestamp

Errors

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

ResourceNotFoundException

The named resource does not exist.

HTTP Status Code: 404

Examples

Example – Get a metric data query definition

The following AWS CLI command retrieves a saved definition by its ID. Replace the ID with your definition ID. The JSON response follows the command.

Sample Request



PROMPT> aws cloudwatch get-metric-data-query-definition \
    --id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111

Sample Response



{
    "Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "Arn": "arn:aws:cloudwatch:us-east-1:111122223333:metric-query-definition/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
    "Path": "ec2/top-cpu-instances",
    "Expression": "SELECT AVG(CPUUtilization) FROM SCHEMA(\"AWS/EC2\", InstanceId) GROUP BY InstanceId ORDER BY AVG() DESC LIMIT 10",
    "Type": "SQL",
    "CreatedAt": "2026-11-09T10:30:00Z",
    "UpdatedAt": "2026-11-09T10:30:00Z"
}