Reservations Details - List

Reference

Service:: Consumption

API Version:: 2024-08-01

Lists the reservations details for provided date range. Note: ARM has a payload size limit of 12MB, so currently callers get 400 when the response size exceeds the ARM limit. If the data size is too large, customers may also get 504 as the API timed out preparing the data. In such cases, API call should be made with smaller date ranges or a call to Generate Reservation Details Report API should be made as it is asynchronous and will not run into response size time outs.

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

With optional parameters:

GET https://management.azure.com/{resourceScope}/providers/Microsoft.Consumption/reservationDetails?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 details 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.
$filter	query		string	Filter reservation details by date range. 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	ReservationDetailsListResult	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

ReservationDetailsByBillingAccountId

ReservationDetailsByBillingProfileId

ReservationDetailsByBillingProfileIdReservationId

ReservationDetailsByBillingAccountId

Sample request

HTTP

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

Sample response

Status code:: 200

{
  "value": [
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/12345/providers/Microsoft.Consumption/reservationDetails/reservationDetails_Id1",
      "name": "reservationDetails_Id1",
      "type": "Microsoft.Consumption/reservationDetails",
      "tags": null,
      "properties": {
        "reservationOrderId": "00000000-0000-0000-0000-000000000000",
        "reservationId": "00000000-0000-0000-0000-000000000000",
        "usageDate": "2017-11-30T00:00:00-08:00",
        "skuName": "Standard_D2s_v3",
        "instanceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/sqlh1/providers/microsoft.compute/virtualmachines/sqlh1",
        "totalReservedQuantity": 0,
        "reservedHours": 48,
        "usedHours": 0.6,
        "instanceFlexibilityGroup": "DSv3 Series",
        "instanceFlexibilityRatio": "1"
      }
    }
  ]
}

ReservationDetailsByBillingProfileId

Sample request

HTTP

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:2468/billingProfiles/13579/providers/Microsoft.Consumption/reservationDetails?startDate=2019-09-01&endDate=2019-10-31&api-version=2024-08-01

Sample response

Status code:: 200

{
  "value": [
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/12345:2468/billingProfiles/13579/providers/Microsoft.Consumption/reservationDetails/reservationDetails_Id1",
      "name": "reservationDetails_Id1",
      "type": "Microsoft.Consumption/reservationDetails",
      "tags": null,
      "properties": {
        "reservationOrderId": "00000000-0000-0000-0000-000000000000",
        "reservationId": "00000000-0000-0000-0000-000000000000",
        "usageDate": "2019-09-30T00:00:00-08:00",
        "skuName": "Standard_D2s_v3",
        "instanceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/sqlh1/providers/microsoft.compute/virtualmachines/sqlh1",
        "totalReservedQuantity": 0,
        "reservedHours": 48,
        "usedHours": 0.6,
        "instanceFlexibilityGroup": "DSv3 Series",
        "instanceFlexibilityRatio": "1"
      }
    }
  ]
}

ReservationDetailsByBillingProfileIdReservationId

Sample request

HTTP

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345:2468/billingProfiles/13579/providers/Microsoft.Consumption/reservationDetails?startDate=2019-09-01&endDate=2019-10-31&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/reservationDetails/reservationDetails_Id1",
      "name": "reservationDetails_Id1",
      "type": "Microsoft.Consumption/reservationDetails",
      "tags": null,
      "properties": {
        "reservationOrderId": "9f39ba10-794f-4dcb-8f4b-8d0cb47c27dc",
        "reservationId": "1c6b6358-709f-484c-85f1-72e862a0cf3b",
        "usageDate": "2019-09-30T00:00:00-08:00",
        "skuName": "Standard_D2s_v3",
        "instanceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/sqlh1/providers/microsoft.compute/virtualmachines/sqlh1",
        "totalReservedQuantity": 0,
        "reservedHours": 48,
        "usedHours": 0.6,
        "instanceFlexibilityGroup": "DSv3 Series",
        "instanceFlexibilityRatio": "1"
      }
    }
  ]
}

Definitions

Name	Description
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.
ReservationDetail	reservation detail resource.
ReservationDetailsListResult	Result of listing reservation details.

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.

ReservationDetail

reservation detail 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.instanceFlexibilityGroup	string	The instance Flexibility Group.
properties.instanceFlexibilityRatio	string	The instance Flexibility Ratio.
properties.instanceId	string	This identifier is the name of the resource or the fully qualified Resource ID.
properties.kind	string	The reservation kind.
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 for the day. 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	The date on which consumption occurred.
properties.usedHours	number	This is the total hours used by the instance.
tags	object	Resource tags.
type	string	Resource type.

ReservationDetailsListResult

Result of listing reservation details.

Name	Type	Description
nextLink	string	The link (url) to the next page of results.
value	ReservationDetail[]	The list of reservation details.

Share via

Reservations Details - List

URI Parameters

Responses

Security

azure_auth

Scopes

Examples

ReservationDetailsByBillingAccountId

Sample request

Sample response

ReservationDetailsByBillingProfileId

Sample request

Sample response

ReservationDetailsByBillingProfileIdReservationId

Sample request

Sample response

Definitions

ErrorDetails

ErrorResponse

ReservationDetail

ReservationDetailsListResult

Additional resources