Reservations Summaries - List

  • Reference
Service:
Consumption
API Version:
2024-08-01

Lists the reservations summaries for the defined scope daily or monthly grain. Note: ARM has a payload size limit of 12MB, so currently callers get 400 when the response size exceeds the ARM limit. In such cases, API call should be made with smaller date ranges.

GET https://management.azure.com/{resourceScope}/providers/Microsoft.Consumption/reservationSummaries?grain={grain}&api-version=2024-08-01
With optional parameters: 
GET https://management.azure.com/{resourceScope}/providers/Microsoft.Consumption/reservationSummaries?grain={grain}&startDate={startDate}&endDate={endDate}&$filter={$filter}&reservationId={reservationId}&reservationOrderId={reservationOrderId}&api-version=2024-08-01

URI Parameters

Name In Required Type Description
resourceScope
 path True

string

The scope associated with reservations summaries operations. This includes '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}' for BillingAccount scope (legacy), and '/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/billingProfiles/{billingProfileId}' for BillingProfile scope (modern).
api-version
 query True

string

Version of the API to be used with the client request. The current version is 2023-03-01.
grain
 query True

datagrain

Can be daily or monthly
$filter
 query

string

Required only for daily grain. The properties/UsageDate for start date and end date. The filter supports 'le' and 'ge'. Not applicable when querying with billing profile
endDate
 query

string

End date. Only applicable when querying with billing profile
reservationId
 query

string

Reservation Id GUID. Only valid if reservationOrderId is also provided. Filter to a specific reservation
reservationOrderId
 query

string

Reservation Order Id GUID. Required if reservationId is provided. Filter to a specific reservation order
startDate
 query

string

Start date. Only applicable when querying with billing profile

Responses

Name Type Description
200 OK

ReservationSummariesListResult

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

ReservationSummariesDailyWithBillingAccountId
ReservationSummariesDailyWithBillingProfileId
ReservationSummariesMonthlyWithBillingAccountId
ReservationSummariesMonthlyWithBillingProfileId
ReservationSummariesMonthlyWithBillingProfileIdReservationId

ReservationSummariesDailyWithBillingAccountId

Sample request

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345/providers/Microsoft.Consumption/reservationSummaries?grain=daily&$filter=properties/usageDate ge 2017-10-01 AND properties/usageDate le 2017-11-20&api-version=2024-08-01

Sample response

Status code:
200 
{
  "value": [
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/12345/providers/Microsoft.Consumption/reservationSummaries/reservationSummaries_Id1",
      "name": "reservationSummaries_Id1",
      "type": "Microsoft.Consumption/reservationSummaries",
      "tags": null,
      "properties": {
        "reservationOrderId": "00000000-0000-0000-0000-000000000000",
        "reservationId": "00000000-0000-0000-0000-000000000000",
        "skuName": "Standard_B1s",
        "reservedHours": 720,
        "usageDate": "2018-09-01T00:00:00-07:00",
        "usedHours": 0,
        "minUtilizationPercentage": 0,
        "avgUtilizationPercentage": 0,
        "maxUtilizationPercentage": 0
      }
    }
  ]
}

ReservationSummariesDailyWithBillingProfileId

Sample request

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:2468/billingProfiles/13579/providers/Microsoft.Consumption/reservationSummaries?grain=daily&startDate=2017-10-01&endDate=2017-11-20&api-version=2024-08-01

Sample response

Status code:
200 
{
  "value": [
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/12345:2468/billingProfiles/13579/providers/Microsoft.Consumption/reservationSummaries/reservationSummaries_Id1",
      "name": "reservationSummaries_Id1",
      "type": "Microsoft.Consumption/reservationSummaries",
      "tags": null,
      "properties": {
        "reservationOrderId": "00000000-0000-0000-0000-000000000000",
        "reservationId": "00000000-0000-0000-0000-000000000000",
        "skuName": "Standard_B1s",
        "reservedHours": 720,
        "usageDate": "2018-09-01T00:00:00-07:00",
        "usedHours": 0,
        "minUtilizationPercentage": 0,
        "avgUtilizationPercentage": 0,
        "maxUtilizationPercentage": 0
      }
    }
  ]
}

ReservationSummariesMonthlyWithBillingAccountId

Sample request

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345/providers/Microsoft.Consumption/reservationSummaries?grain=monthly&api-version=2024-08-01

Sample response

Status code:
200 
{
  "value": [
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/12345/providers/Microsoft.Consumption/reservationSummaries/reservationSummaries_Id1",
      "name": "reservationSummaries_Id1",
      "type": "Microsoft.Consumption/reservationSummaries",
      "tags": null,
      "properties": {
        "reservationOrderId": "00000000-0000-0000-0000-000000000000",
        "reservationId": "00000000-0000-0000-0000-000000000000",
        "skuName": "Standard_B1s",
        "reservedHours": 720,
        "usageDate": "2018-09-01T00:00:00-07:00",
        "usedHours": 0,
        "minUtilizationPercentage": 0,
        "avgUtilizationPercentage": 0,
        "maxUtilizationPercentage": 0
      }
    }
  ]
}

ReservationSummariesMonthlyWithBillingProfileId

Sample request

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:2468/billingProfiles/13579/providers/Microsoft.Consumption/reservationSummaries?grain=monthly&api-version=2024-08-01

Sample response

Status code:
200 
{
  "value": [
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/12345:2468/billingProfiles/13579/providers/Microsoft.Consumption/reservationSummaries/reservationSummaries_Id1",
      "name": "reservationSummaries_Id1",
      "type": "Microsoft.Consumption/reservationSummaries",
      "tags": null,
      "properties": {
        "reservationOrderId": "00000000-0000-0000-0000-000000000000",
        "reservationId": "00000000-0000-0000-0000-000000000000",
        "skuName": "Standard_B1s",
        "reservedHours": 720,
        "usageDate": "2018-09-01T00:00:00-07:00",
        "usedHours": 0,
        "minUtilizationPercentage": 0,
        "avgUtilizationPercentage": 0,
        "maxUtilizationPercentage": 0
      }
    }
  ]
}

ReservationSummariesMonthlyWithBillingProfileIdReservationId

Sample request

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:2468/billingProfiles/13579/providers/Microsoft.Consumption/reservationSummaries?grain=monthly&reservationId=1c6b6358-709f-484c-85f1-72e862a0cf3b&reservationOrderId=9f39ba10-794f-4dcb-8f4b-8d0cb47c27dc&api-version=2024-08-01

Sample response

Status code:
200 
{
  "value": [
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/12345:2468/billingProfiles/13579/providers/Microsoft.Consumption/reservationSummaries/reservationSummaries_Id1",
      "name": "reservationSummaries_Id1",
      "type": "Microsoft.Consumption/reservationSummaries",
      "tags": null,
      "properties": {
        "reservationOrderId": "9f39ba10-794f-4dcb-8f4b-8d0cb47c27dc",
        "reservationId": "1c6b6358-709f-484c-85f1-72e862a0cf3b",
        "skuName": "Standard_B1s",
        "reservedHours": 720,
        "usageDate": "2018-09-01T00:00:00-07:00",
        "usedHours": 0,
        "minUtilizationPercentage": 0,
        "avgUtilizationPercentage": 0,
        "maxUtilizationPercentage": 0
      }
    }
  ]
}

Definitions

Name Description
datagrain

Can be daily or monthly
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.
ReservationSummariesListResult

Result of listing reservation summaries.
ReservationSummary

reservation summary resource.

datagrain

Can be daily or monthly

Name Type Description
daily

string

Daily grain of data
monthly

string

Monthly grain of data

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.

ReservationSummariesListResult

Result of listing reservation summaries.

Name Type Description
nextLink

string

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

ReservationSummary[]

The list of reservation summaries.

ReservationSummary

reservation summary resource.

Name Type Description
etag

string

The etag for the resource.
id

string

The full qualified ARM ID of an event.
name

string

The ID that uniquely identifies an event.
properties.avgUtilizationPercentage

number

This is average utilization for the entire time range. (day or month depending on the grain)
properties.kind

string

The reservation kind.
properties.maxUtilizationPercentage

number

This is the maximum hourly utilization in the usage time (day or month). E.g. if usage record corresponds to 12/10/2017 and on that for hour 4 and 5, utilization was 100%, this field will return 100% for that day.
properties.minUtilizationPercentage

number

This is the minimum hourly utilization in the usage time (day or month). E.g. if usage record corresponds to 12/10/2017 and on that for hour 4 and 5, utilization was 10%, this field will return 10% for that day
properties.purchasedQuantity

number

This is the purchased quantity for the reservationId.
properties.remainingQuantity

number

This is the remaining quantity for the reservationId.
properties.reservationId

string

The reservation ID is the identifier of a reservation within a reservation order. Each reservation is the grouping for applying the benefit scope and also specifies the number of instances to which the reservation benefit can be applied to.
properties.reservationOrderId

string

The reservation order ID is the identifier for a reservation purchase. Each reservation order ID represents a single purchase transaction. A reservation order contains reservations. The reservation order specifies the VM size and region for the reservations.
properties.reservedHours

number

This is the total hours reserved. E.g. if reservation for 1 instance was made on 1 PM, this will be 11 hours for that day and 24 hours from subsequent days
properties.skuName

string

This is the ARM Sku name. It can be used to join with the serviceType field in additional info in usage records.
properties.totalReservedQuantity

number

This is the total count of instances that are reserved for the reservationId.
properties.usageDate

string

Data corresponding to the utilization record. If the grain of data is monthly, it will be first day of month.
properties.usedHours

number

Total used hours by the reservation
properties.usedQuantity

number

This is the used quantity for the reservationId.
properties.utilizedPercentage

number

This is the utilized percentage for the reservation Id.
tags

object

Resource tags.
type

string

Resource type.