Reservation Recommendation Details - Get

Reference

Service:: Consumption

API Version:: 2024-08-01

Details of a reservation recommendation for what-if analysis of reserved instances.

GET https://management.azure.com/{resourceScope}/providers/Microsoft.Consumption/reservationRecommendationDetails?api-version=2024-08-01&scope={scope}&region={region}&term={term}&lookBackPeriod={lookBackPeriod}&product={product}

With optional parameters:

GET https://management.azure.com/{resourceScope}/providers/Microsoft.Consumption/reservationRecommendationDetails?api-version=2024-08-01&scope={scope}&region={region}&term={term}&lookBackPeriod={lookBackPeriod}&product={product}&$filter={$filter}

URI Parameters

Name	In	Required	Type	Description
resourceScope	path	True	string	The scope associated with reservation recommendation details operations. This includes '/subscriptions/{subscriptionId}/' for subscription scope, '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' for resource group scope, /providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for BillingAccount scope, and '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}' for billingProfile scope
api-version	query	True	string	Version of the API to be used with the client request. The current version is 2023-03-01.
lookBackPeriod	query	True	lookBackPeriod	Filter the time period on which reservation recommendation results are based.
product	query	True	string	Filter the products for which reservation recommendation results are generated. Examples: Standard_DS1_v2 (for VM), Premium_SSD_Managed_Disks_P30 (for Managed Disks)
region	query	True	string	Used to select the region the recommendation should be generated for.
scope	query	True	scope	Scope of the reservation.
term	query	True	term	Specify length of reservation recommendation term.
$filter	query		string	Used to filter reservation recommendation details by: properties/subscriptionId can be specified for billing account and billing profile paths.

Responses

Name	Type	Description
200 OK	ReservationRecommendationDetailsModel	OK. The request has succeeded.
204 No Content		An empty response is sent when there are no recommendation details.
Other Status Codes	HighCasedErrorResponse	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

ReservationRecommendationsByBillingAccount-Legacy

ReservationRecommendationsByBillingProfile-Modern

ReservationRecommendationsByResourceGroup-Legacy

ReservationRecommendationsBySubscription-Legacy

ReservationRecommendationsByBillingAccount-Legacy

Sample request

HTTP

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/00000000/providers/Microsoft.Consumption/reservationRecommendationDetails?api-version=2024-08-01&scope=Shared&region=eastus&term=P1Y&lookBackPeriod=Last60Days&product=Standard_DS14_v2&$filter=properties/subscriptionId eq 00000000-0000-0000-0000-00000000

Sample response

Status code:: 200

{
  "id": "providers/Microsoft.Billing/billingAccounts/00000000/providers/microsoft.consumption/reservationrecommendationdetails",
  "name": "reservationRecommendationDetails",
  "type": "Microsoft.Consumption/ReservationRecommendationDetails",
  "properties": {
    "currency": "USD",
    "resource": {
      "appliedScopes": [
        "00000000-0000-0000-0000-00000000",
        "00000000-0000-0000-0000-00000000"
      ],
      "onDemandRate": 1.482,
      "product": "Standard_DS14_v2",
      "region": "eastus",
      "reservationRate": 0.70570776255707,
      "resourceType": "virtualmachines"
    },
    "resourceGroup": null,
    "savings": {
      "calculatedSavings": [
        {
          "onDemandCost": 529550.326618951,
          "overageCost": 63253.5935111345,
          "quantity": 220,
          "reservationCost": 223102.452054792,
          "totalReservationCost": 286356.045565927,
          "savings": 243194.281053024
        },
        {
          "onDemandCost": 529550.32661895,
          "overageCost": 149335.025050147,
          "quantity": 179,
          "reservationCost": 181524.267808217,
          "totalReservationCost": 330859.292858364,
          "savings": 198691.033760586
        },
        {
          "onDemandCost": 529550.32661895,
          "overageCost": 195942.319606957,
          "quantity": 157,
          "reservationCost": 159214.022602738,
          "totalReservationCost": 355156.342209695,
          "savings": 174393.984409255
        },
        {
          "onDemandCost": 529550.32661895,
          "overageCost": 30975.2311896299,
          "quantity": 241,
          "reservationCost": 244398.595205477,
          "totalReservationCost": 275373.826395107,
          "savings": 254176.500223843
        }
      ],
      "lookBackPeriod": 60,
      "recommendedQuantity": 253,
      "reservationOrderTerm": "P1Y",
      "savingsType": "instance",
      "unitOfMeasure": "hour"
    },
    "scope": "Shared",
    "usage": {
      "firstConsumptionDate": "2019-11-27T00:00:00",
      "lastConsumptionDate": "2020-01-25T21:00:00",
      "lookBackUnitType": "virtualMachine quantity",
      "usageData": [
        275.95003899999995,
        275.916705,
        276,
        276,
        275.916725,
        275.916705,
        275.98335299999997,
        276,
        276,
        276,
        276,
        276,
        275.98335299999997,
        276,
        276,
        276,
        276,
        275.933352
      ],
      "usageGrain": "hourly"
    }
  }
}

Status code:: 204

ReservationRecommendationsByBillingProfile-Modern

Sample request

HTTP

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/00000000-0000-0000-0000-00000000:00000000-0000-0000-0000-00000000/billingProfiles/00000000-0000-0000-0000-00000000/providers/Microsoft.Consumption/reservationRecommendationDetails?api-version=2024-08-01&scope=Shared&region=australiaeast&term=P1Y&lookBackPeriod=Last7Days&product=Standard_B2s&$filter=properties/subscriptionId eq 00000000-0000-0000-0000-00000000

Sample response

Status code:: 200

{
  "id": "providers/Microsoft.Billing/billingAccounts/00000000-0000-0000-0000-00000000:00000000-0000-0000-0000-00000000/billingProfiles/00000000-0000-0000-0000-00000000/providers/microsoft.consumption/reservationrecommendationdetails",
  "name": "reservationRecommendationDetails",
  "type": "Microsoft.Consumption/ReservationRecommendationDetails",
  "properties": {
    "currency": "AUD",
    "resource": {
      "appliedScopes": [
        "00000000-0000-0000-0000-00000000"
      ],
      "onDemandRate": 0.0725,
      "product": "Standard_B2s",
      "region": "australiaeast",
      "reservationRate": 0.04414166531788041,
      "resourceType": "virtualmachines"
    },
    "resourceGroup": null,
    "savings": {
      "calculatedSavings": [
        {
          "onDemandCost": 632.8844720496894,
          "overageCost": 0,
          "quantity": 1,
          "reservationCost": 387.74038815226174,
          "totalReservationCost": 387.74038815226174,
          "savings": 245.1440838974277
        }
      ],
      "lookBackPeriod": 7,
      "recommendedQuantity": 1,
      "reservationOrderTerm": "P1Y",
      "savingsType": "instance",
      "unitOfMeasure": "hour"
    },
    "scope": "Shared",
    "usage": {
      "firstConsumptionDate": "2020-01-19T00:00:00",
      "lastConsumptionDate": "2020-01-25T17:00:00",
      "lookBackUnitType": "virtualMachine quantity",
      "usageData": [
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        0
      ],
      "usageGrain": "hourly"
    }
  }
}

Status code:: 204

ReservationRecommendationsByResourceGroup-Legacy

Sample request

HTTP

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-00000000/resourceGroups/testGroup/providers/Microsoft.Consumption/reservationRecommendationDetails?api-version=2024-08-01&scope=Single&region=westus&term=P3Y&lookBackPeriod=Last30Days&product=Standard_DS13_v2

Sample response

Status code:: 200

{
  "id": "subscriptions/00000000-0000-0000-0000-00000000/resourceGroups/testGroup/providers/microsoft.consumption/reservationrecommendationdetails",
  "name": "reservationRecommendationDetails",
  "type": "Microsoft.Consumption/ReservationRecommendationDetails",
  "properties": {
    "currency": "USD",
    "resource": {
      "appliedScopes": [
        "00000000-0000-0000-0000-00000000",
        "testGroup"
      ],
      "onDemandRate": 0.519,
      "product": "Standard_DS13_v2",
      "region": "westus",
      "reservationRate": 0.302549467275493,
      "resourceType": "virtualmachines"
    },
    "resourceGroup": "testGroup",
    "savings": {
      "calculatedSavings": [
        {
          "onDemandCost": 368.4813602070006,
          "overageCost": 0,
          "quantity": 2,
          "reservationCost": 429.01514459665,
          "totalReservationCost": 429.01514459665,
          "savings": -60.5337843896494
        },
        {
          "onDemandCost": 368.481360207,
          "overageCost": 1.557,
          "quantity": 1,
          "reservationCost": 214.507572298325,
          "totalReservationCost": 216.064572298325,
          "savings": 152.416787908675
        }
      ],
      "lookBackPeriod": 30,
      "recommendedQuantity": 1,
      "reservationOrderTerm": "P3Y",
      "savingsType": "instance",
      "unitOfMeasure": "hour"
    },
    "scope": "Single",
    "usage": {
      "firstConsumptionDate": "2020-02-03T00:00:00",
      "lastConsumptionDate": "2020-03-03T13:00:00",
      "lookBackUnitType": "virtualMachine quantity",
      "usageData": [
        1,
        1,
        1,
        1,
        1,
        1
      ],
      "usageGrain": "hourly"
    }
  }
}

Status code:: 204

ReservationRecommendationsBySubscription-Legacy

Sample request

HTTP

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-00000000/providers/Microsoft.Consumption/reservationRecommendationDetails?api-version=2024-08-01&scope=Single&region=westus&term=P3Y&lookBackPeriod=Last30Days&product=Standard_DS13_v2

Sample response

Status code:: 200

{
  "id": "subscriptions/00000000-0000-0000-0000-00000000/providers/microsoft.consumption/reservationrecommendationdetails",
  "name": "reservationRecommendationDetails",
  "type": "Microsoft.Consumption/ReservationRecommendationDetails",
  "properties": {
    "currency": "USD",
    "resource": {
      "appliedScopes": [
        "00000000-0000-0000-0000-00000000"
      ],
      "onDemandRate": 0.519,
      "product": "Standard_DS13_v2",
      "region": "westus",
      "reservationRate": 0.302549467275493,
      "resourceType": "virtualmachines"
    },
    "resourceGroup": null,
    "savings": {
      "calculatedSavings": [
        {
          "onDemandCost": 368.4813602070006,
          "overageCost": 0,
          "quantity": 2,
          "reservationCost": 429.01514459665,
          "totalReservationCost": 429.01514459665,
          "savings": -60.5337843896494
        },
        {
          "onDemandCost": 368.481360207,
          "overageCost": 1.557,
          "quantity": 1,
          "reservationCost": 214.507572298325,
          "totalReservationCost": 216.064572298325,
          "savings": 152.416787908675
        }
      ],
      "lookBackPeriod": 30,
      "recommendedQuantity": 1,
      "reservationOrderTerm": "P3Y",
      "savingsType": "instance",
      "unitOfMeasure": "hour"
    },
    "scope": "Single",
    "usage": {
      "firstConsumptionDate": "2020-02-03T00:00:00",
      "lastConsumptionDate": "2020-03-03T13:00:00",
      "lookBackUnitType": "virtualMachine quantity",
      "usageData": [
        1,
        1,
        1,
        1,
        1,
        1
      ],
      "usageGrain": "hourly"
    }
  }
}

Status code:: 204

Definitions

Name	Description
HighCasedErrorDetails	The details of the error.
HighCasedErrorResponse	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.
lookBackPeriod	Filter the time period on which reservation recommendation results are based.
ReservationRecommendationDetailsCalculatedSavingsProperties	Details of estimated savings. The costs and savings are estimated for the term.
ReservationRecommendationDetailsModel	Reservation recommendation details.
ReservationRecommendationDetailsResourceProperties	Details of the resource.
ReservationRecommendationDetailsSavingsProperties	Details of the estimated savings.
ReservationRecommendationDetailsUsageProperties	Details about historical usage data that has been used for computing the recommendation.
scope	Scope of the reservation.
term	Specify length of reservation recommendation term.

HighCasedErrorDetails

The details of the error.

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

HighCasedErrorResponse

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	HighCasedErrorDetails	The details of the error.

lookBackPeriod

Filter the time period on which reservation recommendation results are based.

Name	Type	Description
Last30Days	string	Use 30 days of data for recommendations
Last60Days	string	Use 60 days of data for recommendations
Last7Days	string	Use 7 days of data for recommendations

ReservationRecommendationDetailsCalculatedSavingsProperties

Details of estimated savings. The costs and savings are estimated for the term.

Name	Type	Description
onDemandCost	number	The cost without reservation. Includes hardware and software cost.
overageCost	number	Hardware and software cost of the resources not covered by the reservation.
quantity	number	The quantity for calculated savings.
reservationCost	number	Hardware cost of the resources covered by the reservation.
reservedUnitCount	number	The number of reserved units used to calculate savings. Always 1 for virtual machines.
savings	number	The amount saved by purchasing the recommended quantity of reservation. This is equal to onDemandCost - totalReservationCost.
totalReservationCost	number	Reservation cost + software cost of the resources covered by the reservation + overage cost.

ReservationRecommendationDetailsModel

Reservation recommendation details.

Name	Type	Description
etag	string	The etag for the resource.
id	string	The full qualified ARM ID of an event.
location	string	Resource Location.
name	string	The ID that uniquely identifies an event.
properties.currency	string	An ISO 4217 currency code identifier for the costs and savings
properties.resource	ReservationRecommendationDetailsResourceProperties	Resource specific properties.
properties.resourceGroup	string	Resource Group.
properties.savings	ReservationRecommendationDetailsSavingsProperties	Savings information for the recommendation.
properties.scope	string	Scope of the reservation, ex: Single or Shared.
properties.usage	ReservationRecommendationDetailsUsageProperties	Historical usage details used to calculate the estimated savings.
sku	string	Resource sku
tags	object	Resource tags.
type	string	Resource type.

ReservationRecommendationDetailsResourceProperties

Details of the resource.

Name	Type	Description
appliedScopes	string[]	List of subscriptions for which the reservation is applied.
onDemandRate	number	Hourly on-demand rate of the resource. Includes only hardware rate i.e, software rate is not included.
product	string	Azure product ex: Standard_E8s_v3 etc.
region	string	Azure resource region ex:EastUS, WestUS etc.
reservationRate	number	Hourly reservation rate of the resource. Varies based on the term.
resourceType	string	The azure resource type.

ReservationRecommendationDetailsSavingsProperties

Details of the estimated savings.

Name	Type	Description
calculatedSavings	ReservationRecommendationDetailsCalculatedSavingsProperties[]	List of calculated savings.
lookBackPeriod	integer	Number of days of usage to look back used for computing the recommendation.
recommendedQuantity	number	Number of recommended units of the resource.
reservationOrderTerm	string	Term period of the reservation. ex: P1M, P1Y or P3Y.
savingsType	string	Type of savings, ex: instance.
unitOfMeasure	string	Measurement unit ex: hour etc.

ReservationRecommendationDetailsUsageProperties

Details about historical usage data that has been used for computing the recommendation.

Name	Type	Description
firstConsumptionDate	string	The first usage date used for looking back for computing the recommendation.
lastConsumptionDate	string	The last usage date used for looking back for computing the recommendation.
lookBackUnitType	string	What the usage data values represent ex: virtual machine instance.
usageData	number[]	The breakdown of historical resource usage. The values are in the order of usage between the firstConsumptionDate and the lastConsumptionDate.
usageGrain	string	The grain of the values represented in the usage data ex: hourly.

scope

Scope of the reservation.

Name	Type	Description
Shared	string
Single	string

term

Specify length of reservation recommendation term.

Name	Type	Description
P1M	string	1 month reservation term
P1Y	string	1 year reservation term
P3Y	string	3 year reservation term

Share via

Reservation Recommendation Details - Get

URI Parameters

Responses

Security

azure_auth

Scopes

Examples

ReservationRecommendationsByBillingAccount-Legacy

Sample request

Sample response

ReservationRecommendationsByBillingProfile-Modern

Sample request

Sample response

ReservationRecommendationsByResourceGroup-Legacy

Sample request

Sample response

ReservationRecommendationsBySubscription-Legacy

Sample request

Sample response

Definitions

HighCasedErrorDetails

HighCasedErrorResponse

lookBackPeriod

ReservationRecommendationDetailsCalculatedSavingsProperties

ReservationRecommendationDetailsModel

ReservationRecommendationDetailsResourceProperties

ReservationRecommendationDetailsSavingsProperties

ReservationRecommendationDetailsUsageProperties

scope

term

Additional resources