Benefit Recommendations - List

Reference

Service:: Cost Management

API Version:: 2023-11-01

List of recommendations for purchasing savings plan.

GET https://management.azure.com/{billingScope}/providers/Microsoft.CostManagement/benefitRecommendations?api-version=2023-11-01

With optional parameters:

GET https://management.azure.com/{billingScope}/providers/Microsoft.CostManagement/benefitRecommendations?$filter={$filter}&$orderby={$orderby}&$expand={$expand}&api-version=2023-11-01

URI Parameters

Name	In	Required	Type	Description
billingScope	path	True	string	The scope associated with benefit recommendation operations. This includes '/subscriptions/{subscriptionId}/' for subscription scope, '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' for resource group scope, /providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for enterprise agreement scope, and '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}' for billing profile scope
api-version	query	True	string	The API version to use for this operation.
$expand	query		string	May be used to expand the properties by: properties/usage, properties/allRecommendationDetails
$filter	query		string	Can be used to filter benefitRecommendations by: properties/scope with allowed values ['Single', 'Shared'] and default value 'Shared'; and properties/lookBackPeriod with allowed values ['Last7Days', 'Last30Days', 'Last60Days'] and default value 'Last60Days'; properties/term with allowed values ['P1Y', 'P3Y'] and default value 'P3Y'; properties/subscriptionId; properties/resourceGroup
$orderby	query		string	May be used to order the recommendations by: properties/armSkuName. For the savings plan, the results are in order by default. There is no need to use this clause.

Responses

Name	Type	Description
200 OK	benefitRecommendationsListResult	OK. The request has succeeded.
Other Status Codes	ErrorResponse	Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

BenefitRecommendationsBillingAccountList

Sample Request

HTTP

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/123456/providers/Microsoft.CostManagement/benefitRecommendations?$filter=properties/lookBackPeriod eq 'Last7Days' AND properties/term eq 'P1Y'&$expand=properties/usage,properties/allRecommendationDetails&api-version=2023-11-01

Sample Response

Status code:: 200

{
  "value": [
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/123456/providers/Microsoft.CostManagement/benefitRecommendations/00000000-0000-0000-0000-000000000000",
      "name": "00000000-0000-0000-0000-000000000000",
      "type": "Microsoft.CostManagement/benefitRecommendations",
      "kind": "SavingsPlan",
      "properties": {
        "firstConsumptionDate": "2022-10-18T00:00:00Z",
        "lastConsumptionDate": "2022-10-25T00:00:00Z",
        "lookBackPeriod": "Last7Days",
        "totalHours": 168,
        "usage": {
          "usageGrain": "Hourly",
          "charges": [
            1,
            1,
            0,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            1,
            2,
            2,
            2,
            2
          ]
        },
        "armSkuName": "Compute_Savings_Plan",
        "term": "P1Y",
        "commitmentGranularity": "Hourly",
        "currencyCode": "USD",
        "costWithoutBenefit": 218.267,
        "scope": "Shared",
        "recommendationDetails": {
          "averageUtilizationPercentage": 99.33,
          "coveragePercentage": 54.609,
          "commitmentAmount": 0.164,
          "overageCost": 144.841,
          "benefitCost": 52.002,
          "savingsAmount": 21.424,
          "savingsPercentage": 9.815,
          "totalCost": 196.843,
          "wastageCost": 0.035
        },
        "allRecommendationDetails": {
          "value": [
            {
              "averageUtilizationPercentage": 99.33,
              "coveragePercentage": 54.609,
              "commitmentAmount": 0.164,
              "overageCost": 144.841,
              "benefitCost": 52.002,
              "savingsAmount": 21.424,
              "savingsPercentage": 9.815,
              "totalCost": 196.843,
              "wastageCost": 0.035
            },
            {
              "averageUtilizationPercentage": 81.474,
              "coveragePercentage": 56.748,
              "commitmentAmount": 0.161,
              "overageCost": 120.389,
              "benefitCost": 83.754,
              "savingsAmount": 14.124,
              "savingsPercentage": 6.47,
              "totalCost": 204.143,
              "wastageCost": 0.1
            }
          ]
        }
      }
    }
  ]
}

Definitions

Name	Description
allSavingsBenefitDetails	Benefit recommendation details.
allSavingsList	The list of all benefit recommendations with the recommendation details.
benefitKind	Reservation or SavingsPlan.
benefitRecommendationModel	benefit plan recommendation details.
benefitRecommendationsListResult	Result of listing benefit recommendations.
ErrorDetails	The details of the error.
ErrorResponse	Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message. Some Error responses: 429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "x-ms-ratelimit-microsoft.consumption-retry-after" header. 503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header.
grain	The grain of the usage. Supported values: 'Hourly'
lookBackPeriod	The number of days of usage evaluated for computing the recommendations.
recommendationUsageDetails	On-demand charges between firstConsumptionDate and lastConsumptionDate that were used for computing benefit recommendations.
sharedScopeBenefitRecommendationProperties	The properties of the benefit recommendation when scope is 'Shared'.
singleScopeBenefitRecommendationProperties	The properties of the benefit recommendations when scope is 'Single'.
term	Term period of the benefit. For example, P1Y or P3Y.

allSavingsBenefitDetails

Benefit recommendation details.

Name	Type	Description
averageUtilizationPercentage	number	Estimated average utilization percentage for the 'totalHours' in the look-back period, with this commitment.
benefitCost	number	The estimated cost with benefit for the 'totalHours' in the look-back period. It's equal to (commitmentAmount * totalHours)
commitmentAmount	number	The commitment amount at the commitmentGranularity.
coveragePercentage	number	Estimated benefit coverage percentage for the 'totalHours' in the look-back period, with this commitment.
overageCost	number	The difference between total cost and benefit cost for the 'totalHours' in the look-back period.
savingsAmount	number	The amount saved for the 'totalHours' in the look-back period, by purchasing the recommended quantity of the benefit.
savingsPercentage	number	The savings in percentage for the 'totalHours' in the look-back period, by purchasing the recommended quantity of benefit.
totalCost	number	Total cost, which is sum of benefit cost and overage cost.
wastageCost	number	Estimated unused portion of the 'benefitCost'.

allSavingsList

The list of all benefit recommendations with the recommendation details.

Name	Type	Description
nextLink	string	The link (URL) to the next page of results.
value	allSavingsBenefitDetails[]	The list of benefit recommendations with the recommendation details..

benefitKind

Reservation or SavingsPlan.

Name	Type	Description
IncludedQuantity	string	Benefit is IncludedQuantity.
Reservation	string	Benefit is Reservation.
SavingsPlan	string	Benefit is SavingsPlan.

benefitRecommendationModel

benefit plan recommendation details.

Name	Type	Description
id	string	Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
kind	benefitKind	Reservation or SavingsPlan.
name	string	The name of the resource
properties	benefitRecommendationProperties: sharedScopeBenefitRecommendationProperties singleScopeBenefitRecommendationProperties	The properties of the benefit recommendations.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

benefitRecommendationsListResult

Result of listing benefit recommendations.

Name	Type	Description
nextLink	string	The link (URL) to the next page of results.
value	benefitRecommendationModel[]	The list of benefit recommendations.

ErrorDetails

The details of the error.

Name	Type	Description
code	string	Error code.
message	string	Error message indicating why the operation failed.

ErrorResponse

Error response indicates that the service is not able to process the incoming request. The reason is provided in the error message.

Some Error responses:

429 TooManyRequests - Request is throttled. Retry after waiting for the time specified in the "x-ms-ratelimit-microsoft.consumption-retry-after" header.
503 ServiceUnavailable - Service is temporarily unavailable. Retry after waiting for the time specified in the "Retry-After" header.

Name	Type	Description
error	ErrorDetails	The details of the error.

grain

The grain of the usage. Supported values: 'Hourly'

Name	Type	Description
Daily	string	Hourly grain corresponds to value per day.
Hourly	string	Hourly grain corresponds to value per hour.
Monthly	string	Hourly grain corresponds to value per month.

lookBackPeriod

The number of days of usage evaluated for computing the recommendations.

Name	Type	Description
Last30Days	string	30 days used to look back.
Last60Days	string	60 days used to look back.
Last7Days	string	7 days used to look back.

recommendationUsageDetails

On-demand charges between firstConsumptionDate and lastConsumptionDate that were used for computing benefit recommendations.

Name	Type	Description
charges	number[]	On-demand charges for each hour between firstConsumptionDate and lastConsumptionDate that were used for computing benefit recommendations.
usageGrain	grain	The grain of the usage. Supported values: 'Hourly'

sharedScopeBenefitRecommendationProperties

The properties of the benefit recommendation when scope is 'Shared'.

Name	Type	Description
allRecommendationDetails	allSavingsList	The list of all benefit recommendations with the recommendation details.
armSkuName	string	ARM SKU name. 'Compute_Savings_Plan' for SavingsPlan.
commitmentGranularity	grain	Grain of the proposed commitment amount. Supported values: 'Hourly'
costWithoutBenefit	number	The current cost without benefit, corresponds to 'totalHours' in the look-back period.
currencyCode	string	An ISO 4217 currency code identifier for the costs and savings amounts.
firstConsumptionDate	string	The first usage date used for looking back for computing the recommendations.
lastConsumptionDate	string	The last usage date used for looking back for computing the recommendations.
lookBackPeriod	lookBackPeriod	The number of days of usage evaluated for computing the recommendations.
recommendationDetails	allSavingsBenefitDetails	The details of the proposed recommendation.
scope	string: Shared	Benefit scope. For example, Single or Shared.
term	term	Term period of the benefit. For example, P1Y or P3Y.
totalHours	integer	The total hours for which the cost is covered. Its equal to number of records in a property 'properties/usage/charges'.
usage	recommendationUsageDetails	On-demand charges between firstConsumptionDate and lastConsumptionDate that were used for computing benefit recommendations.

singleScopeBenefitRecommendationProperties

The properties of the benefit recommendations when scope is 'Single'.

Name	Type	Description
allRecommendationDetails	allSavingsList	The list of all benefit recommendations with the recommendation details.
armSkuName	string	ARM SKU name. 'Compute_Savings_Plan' for SavingsPlan.
commitmentGranularity	grain	Grain of the proposed commitment amount. Supported values: 'Hourly'
costWithoutBenefit	number	The current cost without benefit, corresponds to 'totalHours' in the look-back period.
currencyCode	string	An ISO 4217 currency code identifier for the costs and savings amounts.
firstConsumptionDate	string	The first usage date used for looking back for computing the recommendations.
lastConsumptionDate	string	The last usage date used for looking back for computing the recommendations.
lookBackPeriod	lookBackPeriod	The number of days of usage evaluated for computing the recommendations.
recommendationDetails	allSavingsBenefitDetails	The details of the proposed recommendation.
resourceGroup	string	The resource group that this single scope recommendation is for. Applicable only if recommendation is for 'Single' scope and 'ResourceGroup' request scope.
scope	string: Single	Benefit scope. For example, Single or Shared.
subscriptionId	string	The subscription ID that this single scope recommendation is for. Applicable only if recommendation is for 'Single' scope.
term	term	Term period of the benefit. For example, P1Y or P3Y.
totalHours	integer	The total hours for which the cost is covered. Its equal to number of records in a property 'properties/usage/charges'.
usage	recommendationUsageDetails	On-demand charges between firstConsumptionDate and lastConsumptionDate that were used for computing benefit recommendations.

term

Term period of the benefit. For example, P1Y or P3Y.

Name	Type	Description
P1Y	string	Benefit term is 1 year.
P3Y	string	Benefit term is 3 years.