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

ListMetricDataQueryDefinitions

Lists the metric data query definitions in your account and Region.

The results are summaries that don't include the expression. To get the full definition, call GetMetricDataQueryDefinition with its ID.

This operation supports pagination. Use the MaxResults and NextToken parameters to retrieve results in multiple calls.

Permissions

To list definitions, you need the cloudwatch:ListMetricDataQueryDefinitions permission. This permission applies to all definitions in the account and Region. The results aren't filtered by tags.

Request Syntax


{
   "MaxResults": number,
   "NextToken": "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.

MaxResults

The maximum number of metric data query definitions to return in one call. The default is 100.

Type: Integer

Valid Range: Minimum value of 1. Maximum value of 100.

Required: No

NextToken

The token returned by a previous call to indicate where to continue retrieving results.

Type: String

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

Pattern: [A-Za-z0-9_-]+

Required: No

Response Syntax


{
   "Items": [ 
      { 
         "Id": "string",
         "Path": "string",
         "Type": "string",
         "UpdatedAt": number
      }
   ],
   "NextToken": "string"
}

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.

Items

A list of metric data query definition summaries.

Type: Array of MetricDataQueryDefinitionSummary objects

NextToken

The token to use when requesting the next set of results. If this field is absent, there are no more results to retrieve.

Type: String

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

Pattern: [A-Za-z0-9_-]+

Errors

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

Examples

Example – List metric data query definitions

The following AWS CLI command lists the metric data query definitions in your account and Region. The JSON response follows the command.

Sample Request



PROMPT> aws cloudwatch list-metric-data-query-definitions

Sample Response



{
    "Items": [
        {
            "Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
            "Path": "ec2/top-cpu-instances",
            "Type": "SQL",
            "UpdatedAt": "2026-11-09T10:30:00Z"
        },
        {
            "Id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE22222",
            "Path": "ec2/cpu-all-instances",
            "Type": "METRIC_MATH",
            "UpdatedAt": "2026-11-08T16:45:00Z"
        }
    ]
}