Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

ListEfficiencyMetrics

Returns cost efficiency metrics aggregated over time and optionally grouped by a specified dimension. The metrics provide insights into your cost optimization progress by tracking estimated savings, spending, and measures how effectively you're optimizing your Cloud resources.

The operation supports both daily and monthly time granularities and allows grouping results by account ID, AWS Region. Results are returned as time-series data, enabling you to analyze trends in your cost optimization performance over the specified time period.

Request Syntax


{
   "granularity": "string",
   "groupBy": "string",
   "maxResults": number,
   "nextToken": "string",
   "orderBy": { 
      "dimension": "string",
      "order": "string"
   },
   "timePeriod": { 
      "end": "string",
      "start": "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.

granularity

The time granularity for the cost efficiency metrics. Specify Daily for metrics aggregated by day, or Monthly for metrics aggregated by month.

Type: String

Valid Values: Daily | Monthly

Required: Yes

groupBy

The dimension by which to group the cost efficiency metrics. Valid values include account ID, AWS Region. When no grouping is specified, metrics are aggregated across all resources in the specified time period.

Type: String

Required: No

maxResults

The maximum number of groups to return in the response. Valid values range from 0 to 1000. Use in conjunction with nextToken to paginate through results when the total number of groups exceeds this limit.

Type: Integer

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

Required: No

nextToken

The token to retrieve the next page of results. This value is returned in the response when the number of groups exceeds the specified maxResults value.

Type: String

Required: No

orderBy

The ordering specification for the results. Defines which dimension to sort by and whether to sort in ascending or descending order.

Type: OrderBy object

Required: No

timePeriod

The time period for which to retrieve the cost efficiency metrics. The start date is inclusive and the end date is exclusive. Dates can be specified in either YYYY-MM-DD format or YYYY-MM format depending on the desired granularity.

Type: TimePeriod object

Required: Yes

Response Syntax


{
   "efficiencyMetricsByGroup": [ 
      { 
         "group": "string",
         "message": "string",
         "metricsByTime": [ 
            { 
               "savings": number,
               "score": number,
               "spend": number,
               "timestamp": "string"
            }
         ]
      }
   ],
   "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.

efficiencyMetricsByGroup

A list of cost efficiency metrics grouped by the specified dimension. Each group contains time-series data points with cost efficiency, potential savings, and optimzable spend for the specified time period.

Type: Array of EfficiencyMetricsByGroup objects

nextToken

The token to retrieve the next page of results. When this value is present in the response, additional groups are available. Pass this token in the nextToken parameter of a subsequent request to retrieve the next page.

Type: String

Errors

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

AccessDeniedException

You are not authorized to use this operation with the given parameters.

HTTP Status Code: 400

InternalServerException

An error on the server occurred during the processing of your request. Try again later.

HTTP Status Code: 500

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 400

ValidationException

The input fails to satisfy the constraints specified by an AWS service.

fields: The list of fields that are invalid.
reason: The reason for the validation exception.

HTTP Status Code: 400