Reservation Recommendations - List

List of recommendations for purchasing reserved instances.

GET https://management.azure.com/{resourceScope}/providers/Microsoft.Consumption/reservationRecommendations?api-version=2024-08-01
GET https://management.azure.com/{resourceScope}/providers/Microsoft.Consumption/reservationRecommendations?$filter={$filter}&api-version=2024-08-01

URI Parameters

Name In Required Type Description
resourceScope
path True

string

The scope associated with reservation recommendations 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.

$filter
query

string

May be used to filter reservationRecommendations by: properties/scope with allowed values ['Single', 'Shared'] and default value 'Single'; properties/resourceType with allowed values ['VirtualMachines', 'SQLDatabases', 'PostgreSQL', 'ManagedDisk', 'MySQL', 'RedHat', 'MariaDB', 'RedisCache', 'CosmosDB', 'SqlDataWarehouse', 'SUSELinux', 'AppService', 'BlockBlob', 'AzureDataExplorer', 'VMwareCloudSimple'] and default value 'VirtualMachines'; and properties/lookBackPeriod with allowed values ['Last7Days', 'Last30Days', 'Last60Days'] and default value 'Last7Days'.

Responses

Name Type Description
200 OK

ReservationRecommendationsListResult

OK. The request has succeeded.

204 No Content

An empty response is sent when there are no recommendations.

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

ReservationRecommendationsByBillingAccount-Legacy
ReservationRecommendationsByBillingAccountFilterForScope
ReservationRecommendationsByBillingProfile-Modern
ReservationRecommendationsByResourceGroup-Legacy
ReservationRecommendationsBySubscription-Legacy
ReservationRecommendationsFilterBySubscriptionForScopeLookBackPeriod-Legacy

ReservationRecommendationsByBillingAccount-Legacy

Sample request

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/123456/providers/Microsoft.Consumption/reservationRecommendations?api-version=2024-08-01

Sample response

{
  "value": [
    {
      "id": "billingAccount/123456/providers/Microsoft.Consumption/reservationRecommendations/00000000-0000-0000-0000-000000000000",
      "name": "00000000-0000-0000-0000-000000000000",
      "type": "Microsoft.Consumption/reservationRecommendations",
      "location": "westus",
      "sku": "Standard_DS1_v2",
      "kind": "legacy",
      "properties": {
        "meterId": "00000000-0000-0000-0000-000000000000",
        "term": "P1Y",
        "costWithNoReservedInstances": 12.0785105,
        "recommendedQuantity": 1,
        "totalCostWithReservedInstances": 11.4899644807748,
        "netSavings": 0.588546019225182,
        "firstUsageDate": "2019-07-07T00:00:00-07:00",
        "scope": "Shared",
        "lookBackPeriod": "Last7Days",
        "instanceFlexibilityRatio": 1,
        "instanceFlexibilityGroup": "DSv2 Series",
        "normalizedSize": "Standard_DS1_v2",
        "recommendedQuantityNormalized": 1,
        "skuProperties": [
          {
            "name": "Cores",
            "value": "1"
          },
          {
            "name": "Ram",
            "value": "1"
          }
        ],
        "totalHours": 701,
        "lastUsageDate": "2019-08-07T00:00:00-07:00"
      }
    },
    {
      "id": "billingAccount/123456/providers/Microsoft.Consumption/reservationRecommendations/00000000-0000-0000-0000-000000000000",
      "name": "00000000-0000-0000-0000-000000000000",
      "type": "Microsoft.Consumption/reservationRecommendations",
      "location": "westus",
      "sku": "Standard_DS1_v2",
      "kind": "legacy",
      "properties": {
        "meterId": "00000000-0000-0000-0000-000000000000",
        "term": "P1Y",
        "costWithNoReservedInstances": 10.0785105,
        "recommendedQuantity": 1,
        "totalCostWithReservedInstances": 13.48,
        "netSavings": 0.68,
        "firstUsageDate": "2019-07-07T00:00:00-07:00",
        "scope": "Shared",
        "lookBackPeriod": "Last7Days",
        "instanceFlexibilityRatio": 1,
        "instanceFlexibilityGroup": "DSv2 Series",
        "normalizedSize": "Standard_DS1",
        "recommendedQuantityNormalized": 1.2,
        "skuProperties": [
          {
            "name": "SkuDisplayName",
            "value": "B"
          },
          {
            "name": "CPU",
            "value": "1"
          }
        ],
        "totalHours": 805,
        "lastUsageDate": "2019-08-09T00:00:00-07:00"
      }
    }
  ],
  "nextLink": "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/reservationRecommendations?api-version=2024-08-01&$skiptoken=AQAAAA%3D%3D&"
}

ReservationRecommendationsByBillingAccountFilterForScope

Sample request

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/123456/providers/Microsoft.Consumption/reservationRecommendations?$filter=properties/scope eq 'Single'&api-version=2024-08-01

Sample response

{
  "value": [
    {
      "kind": "legacy",
      "id": "billingAccount/123456/providers/Microsoft.Consumption/reservationRecommendations/71fd91a7-13b9-4ade-bb11-85cfd6422d9d",
      "name": "71fd91a7-13b9-4ade-bb11-85cfd6422d9d",
      "type": "Microsoft.Consumption/reservationRecommendations",
      "location": "westus3",
      "sku": "Standard_B4ms",
      "properties": {
        "meterId": "9a3781ce-d0dc-5f76-99d7-29eb5aec447f",
        "term": "P1Y",
        "costWithNoReservedInstances": 0.332,
        "recommendedQuantity": 1,
        "totalCostWithReservedInstances": 0.19474885844748857,
        "netSavings": 0.13725114155251145,
        "firstUsageDate": "2024-04-30T07:00:00Z",
        "scope": "Single",
        "lookBackPeriod": "Last7Days",
        "subscriptionId": "00000000-0000-0000-0000-000000000000",
        "resourceType": "virtualmachines",
        "instanceFlexibilityRatio": 8,
        "instanceFlexibilityGroup": "BS Series High Memory",
        "normalizedSize": "Standard_B1ms",
        "recommendedQuantityNormalized": 8,
        "skuProperties": []
      }
    },
    {
      "kind": "legacy",
      "id": "billingAccount/123456/providers/Microsoft.Consumption/reservationRecommendations/904b99c2-baf3-4bff-98ff-a96238ccbc96",
      "name": "904b99c2-baf3-4bff-98ff-a96238ccbc96",
      "type": "Microsoft.Consumption/reservationRecommendations",
      "location": "westus3",
      "sku": "Standard_B4ms",
      "properties": {
        "meterId": "9a3781ce-d0dc-5f76-99d7-29eb5aec447f",
        "term": "P3Y",
        "costWithNoReservedInstances": 0.332,
        "recommendedQuantity": 1,
        "totalCostWithReservedInstances": 0.12511415525114156,
        "netSavings": 0.20688584474885846,
        "firstUsageDate": "2024-04-30T07:00:00Z",
        "scope": "Single",
        "lookBackPeriod": "Last7Days",
        "subscriptionId": "00000000-0000-0000-0000-000000000000",
        "resourceType": "virtualmachines",
        "instanceFlexibilityRatio": 8,
        "instanceFlexibilityGroup": "BS Series High Memory",
        "normalizedSize": "Standard_B1ms",
        "recommendedQuantityNormalized": 8,
        "skuProperties": []
      }
    }
  ]
}

ReservationRecommendationsByBillingProfile-Modern

Sample request

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/123456/billingProfiles/6420/providers/Microsoft.Consumption/reservationRecommendations?api-version=2024-08-01

Sample response

{
  "value": [
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/123456/billingProfiles/6420/providers/Microsoft.Consumption/reservationRecommendations/00000000-0000-0000-0000-000000000000",
      "name": "00000000-0000-0000-0000-000000000000",
      "type": "Microsoft.Consumption/reservationRecommendations",
      "kind": "modern",
      "properties": {
        "costWithNoReservedInstances": {
          "currency": "USD",
          "value": 279881.9457795231
        },
        "firstUsageDate": "2022-08-22T00:00:00Z",
        "instanceFlexibilityGroup": "NA",
        "instanceFlexibilityRatio": 1,
        "location": "westus2",
        "lookBackPeriod": 60,
        "meterId": "30f7049a-b092-42f4-9173-9ec31ab945ad",
        "netSavings": {
          "currency": "USD",
          "value": 153766.87728637524
        },
        "normalizedSize": "SQLDB_BC_Compute_Gen5",
        "recommendedQuantity": 35,
        "recommendedQuantityNormalized": 35,
        "resourceType": "sqldatabases",
        "scope": "Single",
        "skuName": "SQLDB_BC_Compute_Gen5",
        "skuProperties": null,
        "subscriptionId": "c6aa8a01-a744-44a7-a4f1-caad17512f27",
        "term": "P3Y",
        "totalCostWithReservedInstances": {
          "currency": "USD",
          "value": 126115.06849314792
        },
        "totalHours": 717,
        "lastUsageDate": "2022-09-22T00:00:00Z"
      }
    },
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/123456/billingProfiles/6420/providers/Microsoft.Consumption/reservationRecommendations/00000000-0000-0000-0000-000000000000",
      "name": "00000000-0000-0000-0000-000000000000",
      "type": "Microsoft.Consumption/reservationRecommendations",
      "kind": "modern",
      "properties": {
        "costWithNoReservedInstances": {
          "currency": "USD",
          "value": 93208.8596802244
        },
        "firstUsageDate": "2022-08-22T00:00:00Z",
        "instanceFlexibilityGroup": "NA",
        "instanceFlexibilityRatio": 1,
        "location": "westus2",
        "lookBackPeriod": 60,
        "meterId": "30f7049a-b092-42f4-9173-9ec31ab945ad",
        "netSavings": {
          "currency": "USD",
          "value": 32553.85968022456
        },
        "normalizedSize": "SQLDB_BC_Compute_Gen5",
        "recommendedQuantity": 35,
        "recommendedQuantityNormalized": 35,
        "resourceType": "sqldatabases",
        "scope": "Single",
        "skuName": "SQLDB_BC_Compute_Gen5",
        "skuProperties": null,
        "subscriptionId": "c6aa8a01-a744-44a7-a4f1-caad17512f27",
        "term": "P1Y",
        "totalCostWithReservedInstances": {
          "currency": "USD",
          "value": 60654.99999999984
        },
        "totalHours": 527,
        "lastUsageDate": "2022-08-27T00:00:00Z"
      }
    }
  ],
  "nextLink": "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/reservationRecommendations?api-version=2024-08-01&$skiptoken=AQAAAA%3D%3D&"
}

ReservationRecommendationsByResourceGroup-Legacy

Sample request

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/testGroup/providers/Microsoft.Consumption/reservationRecommendations?api-version=2024-08-01

Sample response

{
  "value": [
    {
      "id": "subscriptions/00000000-0000-0000-0000-000000000000/resourceGrouups/testGroup/providers/Microsoft.Consumption/reservationRecommendations/reservationRecommendations1",
      "name": "reservationRecommendations1",
      "type": "Microsoft.Consumption/reservationRecommendations",
      "sku": "Standard_DS1_v2",
      "location": "northeurope",
      "kind": "legacy",
      "properties": {
        "lookBackPeriod": "Last7Days",
        "meterId": "00000000-0000-0000-0000-000000000000",
        "term": "P1Y",
        "costWithNoReservedInstances": 0,
        "recommendedQuantity": 1,
        "totalCostWithReservedInstances": 0,
        "netSavings": 4.634521202630137,
        "firstUsageDate": "2018-03-06T00:00:00Z",
        "scope": "Single",
        "subscriptionId": "00000000-0000-0000-0000-000000000000",
        "totalHours": 427,
        "lastUsageDate": "2018-03-08T00:00:00Z"
      }
    },
    {
      "id": "subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/testGroup/providers/Microsoft.Consumption/reservationRecommendations/reservationRecommendations2",
      "name": "reservationRecommendations2",
      "type": "Microsoft.Consumption/reservationRecommendations",
      "sku": "Standard_DS1_v2",
      "location": "northeurope",
      "kind": "legacy",
      "properties": {
        "lookBackPeriod": "Last7Days",
        "meterId": "00000000-0000-0000-0000-000000000000",
        "term": "P3Y",
        "costWithNoReservedInstances": 0,
        "recommendedQuantity": 1,
        "totalCostWithReservedInstances": 0,
        "netSavings": 7.289315723178081,
        "firstUsageDate": "2018-03-06T00:00:00Z",
        "scope": "Single",
        "subscriptionId": "00000000-0000-0000-0000-000000000000",
        "totalHours": 327,
        "lastUsageDate": "2018-03-09T00:00:00Z"
      }
    }
  ],
  "nextLink": "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/testGroup/providers/Microsoft.Consumption/reservationRecommendations?api-version=2024-08-01&$skiptoken=AQAAAA%3D%3D&"
}

ReservationRecommendationsBySubscription-Legacy

Sample request

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/reservationRecommendations?api-version=2024-08-01

Sample response

{
  "value": [
    {
      "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/reservationRecommendations/reservationRecommendations1",
      "name": "reservationRecommendations1",
      "type": "Microsoft.Consumption/reservationRecommendations",
      "sku": "Standard_DS1_v2",
      "location": "northeurope",
      "kind": "legacy",
      "properties": {
        "lookBackPeriod": "Last7Days",
        "meterId": "00000000-0000-0000-0000-000000000000",
        "term": "P1Y",
        "costWithNoReservedInstances": 0,
        "recommendedQuantity": 1,
        "totalCostWithReservedInstances": 0,
        "netSavings": 4.634521202630137,
        "firstUsageDate": "2018-03-06T00:00:00Z",
        "scope": "Single",
        "subscriptionId": "00000000-0000-0000-0000-000000000000",
        "totalHours": 827,
        "lastUsageDate": "2018-03-10T00:00:00Z"
      }
    },
    {
      "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/reservationRecommendations/reservationRecommendations2",
      "name": "reservationRecommendations2",
      "type": "Microsoft.Consumption/reservationRecommendations",
      "sku": "Standard_DS1_v2",
      "location": "northeurope",
      "kind": "legacy",
      "properties": {
        "lookBackPeriod": "Last7Days",
        "meterId": "00000000-0000-0000-0000-000000000000",
        "term": "P3Y",
        "costWithNoReservedInstances": 0,
        "recommendedQuantity": 1,
        "totalCostWithReservedInstances": 0,
        "netSavings": 7.289315723178081,
        "firstUsageDate": "2018-03-06T00:00:00Z",
        "scope": "Single",
        "subscriptionId": "00000000-0000-0000-0000-000000000000",
        "totalHours": 927,
        "lastUsageDate": "2018-03-15T00:00:00Z"
      }
    }
  ],
  "nextLink": "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/reservationRecommendations?api-version=2024-08-01&$skiptoken=AQAAAA%3D%3D&"
}

ReservationRecommendationsFilterBySubscriptionForScopeLookBackPeriod-Legacy

Sample request

GET https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/reservationRecommendations?$filter=properties/scope eq 'Single' AND properties/lookBackPeriod eq 'Last7Days'&api-version=2024-08-01

Sample response

{
  "value": [
    {
      "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/reservationRecommendations/reservationRecommendations1",
      "name": "reservationRecommendations1",
      "type": "Microsoft.Consumption/reservationRecommendations",
      "sku": "Standard_DS1_v2",
      "location": "northeurope",
      "kind": "legacy",
      "properties": {
        "lookBackPeriod": "Last7Days",
        "meterId": "00000000-0000-0000-0000-000000000000",
        "term": "P1Y",
        "costWithNoReservedInstances": 0,
        "recommendedQuantity": 1,
        "totalCostWithReservedInstances": 0,
        "netSavings": 4.634521202630137,
        "firstUsageDate": "2018-03-06T00:00:00Z",
        "scope": "Single",
        "skuProperties": [
          {
            "name": "Cores",
            "value": "1"
          },
          {
            "name": "Ram",
            "value": "1"
          }
        ],
        "subscriptionId": "00000000-0000-0000-0000-000000000000",
        "totalHours": 527,
        "lastUsageDate": "2018-03-15T00:00:00Z"
      }
    },
    {
      "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/reservationRecommendations/reservationRecommendations2",
      "name": "reservationRecommendations2",
      "type": "Microsoft.Consumption/reservationRecommendations",
      "sku": "Standard_DS1_v2",
      "location": "northeurope",
      "kind": "legacy",
      "properties": {
        "lookBackPeriod": "Last7Days",
        "meterId": "00000000-0000-0000-0000-000000000000",
        "term": "P3Y",
        "costWithNoReservedInstances": 0,
        "recommendedQuantity": 1,
        "totalCostWithReservedInstances": 0,
        "netSavings": 7.289315723178081,
        "firstUsageDate": "2018-03-06T00:00:00Z",
        "scope": "Single",
        "skuProperties": [
          {
            "name": "SkuDisplayName",
            "value": "B"
          },
          {
            "name": "CPU",
            "value": "1"
          }
        ],
        "subscriptionId": "00000000-0000-0000-0000-000000000000",
        "totalHours": 427,
        "lastUsageDate": "2018-03-08T00:00:00Z"
      }
    }
  ],
  "nextLink": "https://management.azure.com/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Consumption/reservationRecommendations?api-version=2024-08-01&$filter=properties/scope+eq+'Single'+AND+properties/lookBackPeriod+eq+'Last7Days'&$skiptoken=AQAAAA%3D%3D&"
}

Definitions

Name Description
amount

The amount plus currency .

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.

  • 504 Gateway Timeout - Service timed out while processing the request. Reduce the date range in the request, if possible.

LegacyReservationRecommendation

Legacy reservation recommendation.

ModernReservationRecommendation

Modern reservation recommendation.

ReservationRecommendationsListResult

Result of listing reservation recommendations.

SkuProperty

The Sku property

amount

The amount plus currency .

Name Type Description
currency

string

Amount currency.

value

number

Amount.

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.

  • 504 Gateway Timeout - Service timed out while processing the request. Reduce the date range in the request, if possible.

Name Type Description
error

ErrorDetails

The details of the error.

LegacyReservationRecommendation

Legacy reservation recommendation.

Name Type Description
etag

string

The etag for the resource.

id

string

The full qualified ARM ID of an event.

kind string:

legacy

Specifies the kind of reservation recommendation.

location

string

Resource location

name

string

The ID that uniquely identifies an event.

properties.costWithNoReservedInstances

number

The total amount of cost without reserved instances.

properties.firstUsageDate

string

The usage date for looking back.

properties.instanceFlexibilityGroup

string

The instance Flexibility Group.

properties.instanceFlexibilityRatio

number

The instance Flexibility Ratio.

properties.lastUsageDate

string

The last usage date used for looking back for computing the recommendation.

properties.lookBackPeriod

string

The number of days of usage to look back for recommendation.

properties.meterId

string

The meter id (GUID)

properties.netSavings

number

Total estimated savings with reserved instances.

properties.normalizedSize

string

The normalized Size.

properties.recommendedQuantity

number

Recommended quality for reserved instances.

properties.recommendedQuantityNormalized

number

The recommended Quantity Normalized.

properties.resourceType

string

The azure resource type.

properties.scope

string

Shared or single recommendation.

properties.skuProperties

SkuProperty[]

List of sku properties

properties.term

string

Term period of the reservation. ex: P1M, P1Y or P3Y.

properties.totalCostWithReservedInstances

number

The total amount of cost with reserved instances.

properties.totalHours

integer

The total hours for which the cost is covered.

sku

string

Resource sku

tags

object

Resource tags.

type

string

Resource type.

ModernReservationRecommendation

Modern reservation recommendation.

Name Type Description
etag

string

The etag for the resource.

id

string

The full qualified ARM ID of an event.

kind string:

modern

Specifies the kind of reservation recommendation.

location

string

Resource location

name

string

The ID that uniquely identifies an event.

properties.costWithNoReservedInstances

amount

The total amount of cost without reserved instances.

properties.firstUsageDate

string

The usage date for looking back.

properties.instanceFlexibilityGroup

string

The instance Flexibility Group.

properties.instanceFlexibilityRatio

number

The instance Flexibility Ratio.

properties.lastUsageDate

string

The last usage date used for looking back for computing the recommendation.

properties.location

string

Resource Location.

properties.lookBackPeriod

integer

The number of days of usage to look back for recommendation.

properties.meterId

string

The meter id (GUID)

properties.netSavings

amount

Total estimated savings with reserved instances.

properties.normalizedSize

string

The normalized Size.

properties.recommendedQuantity

number

Recommended quality for reserved instances.

properties.recommendedQuantityNormalized

number

The recommended Quantity Normalized.

properties.resourceType

string

Resource type.

properties.scope

string

Shared or single recommendation.

properties.skuName

string

This is the ARM Sku name.

properties.skuProperties

SkuProperty[]

List of sku properties

properties.term

string

Term period of the reservation. ex: P1M, P1Y or P3Y.

properties.totalCostWithReservedInstances

amount

The total amount of cost with reserved instances.

properties.totalHours

integer

The total hours for which the cost is covered.

sku

string

Resource sku

tags

object

Resource tags.

type

string

Resource type.

ReservationRecommendationsListResult

Result of listing reservation recommendations.

Name Type Description
nextLink

string

The link (url) to the next page of results.

previousLink

string

The link (url) to the previous page of results.

value ReservationRecommendation[]:

The list of reservation recommendations.

SkuProperty

The Sku property

Name Type Description
name

string

The name of sku property.

value

string

The value of sku property.