Benefit Recommendations - List

Reference

Service:: Cost Management

API Version:: 2024-08-01

List of recommendations for purchasing savings plan.

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

With optional parameters:

GET https://management.azure.com/{billingScope}/providers/Microsoft.CostManagement/benefitRecommendations?$filter={$filter}&$orderby={$orderby}&$expand={$expand}&api-version=2024-08-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 minLength: 1	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=2024-08-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

Object

Benefit recommendation details.

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

allSavingsList

Object

The list of all benefit recommendations with the recommendation details.

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

benefitKind

Enumeration

Reservation or SavingsPlan.

Value	Description
IncludedQuantity	Benefit is IncludedQuantity.
Reservation	Benefit is Reservation.
SavingsPlan	Benefit is SavingsPlan.

benefitRecommendationModel

Object

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

Object

Result of listing benefit recommendations.

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

ErrorDetails

Object

The details of the error.

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

ErrorResponse

Object

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

Enumeration

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

Value	Description
Daily	Hourly grain corresponds to value per day.
Hourly	Hourly grain corresponds to value per hour.
Monthly	Hourly grain corresponds to value per month.

lookBackPeriod

Enumeration

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

Value	Description
Last30Days	30 days used to look back.
Last60Days	60 days used to look back.
Last7Days	7 days used to look back.

recommendationUsageDetails

Object

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

Name	Type	Description
charges	number[] (decimal)	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

Object

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 (decimal)	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 (date-time)	The first usage date used for looking back for computing the recommendations.
lastConsumptionDate	string (date-time)	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 (int32)	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

Object

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 (decimal)	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 (date-time)	The first usage date used for looking back for computing the recommendations.
lastConsumptionDate	string (date-time)	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 (int32)	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

Enumeration

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

Value	Description
P1Y	Benefit term is 1 year.
P3Y	Benefit term is 3 years.

Share via

Benefit Recommendations - List

URI Parameters

Responses

Security

azure_auth

Scopes

Examples

BenefitRecommendationsBillingAccountList

Sample request

Sample response

Definitions

allSavingsBenefitDetails

allSavingsList

benefitKind

benefitRecommendationModel

benefitRecommendationsListResult

ErrorDetails

ErrorResponse

grain

lookBackPeriod

recommendationUsageDetails

sharedScopeBenefitRecommendationProperties

singleScopeBenefitRecommendationProperties

term

Additional resources