Benefit Utilization Summaries - List By Savings Plan Order

Service:: Cost Management

API Version:: 2025-03-01

Lists the savings plan utilization summaries for daily or monthly grain.

GET https://management.azure.com/providers/Microsoft.BillingBenefits/savingsPlanOrders/{savingsPlanOrderId}/providers/Microsoft.CostManagement/benefitUtilizationSummaries?api-version=2025-03-01

With optional parameters:

GET https://management.azure.com/providers/Microsoft.BillingBenefits/savingsPlanOrders/{savingsPlanOrderId}/providers/Microsoft.CostManagement/benefitUtilizationSummaries?api-version=2025-03-01&$filter={$filter}&grainParameter={grainParameter}

URI Parameters

Name	In	Required	Type	Description
savingsPlanOrderId	path	True	string	Savings plan order ID.
api-version	query	True	string minLength: 1	The API version to use for this operation.
$filter	query		string	Supports filtering by properties/usageDate.
grainParameter	query		grainParameter	Grain.

Responses

Name	Type	Description
200 OK	BenefitUtilizationSummariesListResult	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

SavingsPlanUtilizationSummariesDaily

Sample request

HTTP

GET https://management.azure.com/providers/Microsoft.BillingBenefits/savingsPlanOrders/66cccc66-6ccc-6c66-666c-66cc6c6c66c6/providers/Microsoft.CostManagement/benefitUtilizationSummaries?api-version=2025-03-01

Sample response

Status code:: 200

{
  "value": [
    {
      "id": "/providers/Microsoft.BillingBenefits/savingsPlanOrders/66cccc66-6ccc-6c66-666c-66cc6c6c66c6/providers/Microsoft.CostManagement/benefitUtilizationSummaries/66cccc66-6ccc-6c66-666c-66cc6c6c66c6_222d22dd-d2d2-2dd2-222d-2dd2222ddddd_20211116",
      "kind": "SavingsPlan",
      "name": "66cccc66-6ccc-6c66-666c-66cc6c6c66c6_222d22dd-d2d2-2dd2-222d-2dd2222ddddd_20211116",
      "type": "Microsoft.CostManagement/benefitUtilizationSummaries",
      "properties": {
        "armSkuName": "Compute_Savings_Plan",
        "avgUtilizationPercentage": 90,
        "benefitOrderId": "/providers/Microsoft.BillingBenefits/savingsPlanOrders/66cccc66-6ccc-6c66-666c-66cc6c6c66c6",
        "benefitId": "/providers/Microsoft.BillingBenefits/savingsPlanOrders/66cccc66-6ccc-6c66-666c-66cc6c6c66c6/savingsPlans/222d22dd-d2d2-2dd2-222d-2dd2222ddddd",
        "benefitType": "SavingsPlan",
        "maxUtilizationPercentage": 100,
        "minUtilizationPercentage": 80,
        "usageDate": "2022-10-16T00:00:00Z"
      }
    }
  ]
}

Definitions

Name	Description
benefitKind	Reservation or SavingsPlan.
BenefitUtilizationSummariesListResult	List of benefit utilization summaries.
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.
grainParameter	Grain.
IncludedQuantityUtilizationSummary	Included Quantity utilization summary resource.
SavingsPlanUtilizationSummary	Savings plan utilization summary resource.

benefitKind

Enumeration

Reservation or SavingsPlan.

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

BenefitUtilizationSummariesListResult

Object

List of benefit utilization summaries.

Name	Type	Description
nextLink	string (uri)	The link (URL) to the next page of results.
value	BenefitUtilizationSummary[]: IncludedQuantityUtilizationSummary[] SavingsPlanUtilizationSummary[]	The list of benefit utilization summaries.

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.

grainParameter

Enumeration

Grain.

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

IncludedQuantityUtilizationSummary

Object

Included Quantity utilization summary resource.

Name	Type	Description
id	string	Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
kind	string: IncludedQuantity	Supported values: 'SavingsPlan'.
name	string	The name of the resource
properties.armSkuName	string	ARM SKU name. For example, 'Compute_Savings_Plan' for savings plan.
properties.benefitId	string	The benefit ID is the identifier of the benefit.
properties.benefitOrderId	string	The benefit order ID is the identifier for a benefit purchase.
properties.benefitType	benefitKind	The benefit type. Supported values: 'SavingsPlan'.
properties.usageDate	string (date-time)	Date corresponding to the utilization summary record. If the grain of data is monthly, value for this field will be first day of the month.
properties.utilizationPercentage	number (decimal)	This is the utilized percentage for the benefit ID.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

SavingsPlanUtilizationSummary

Object

Savings plan utilization summary resource.

Name	Type	Description
id	string	Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
kind	string: SavingsPlan	Supported values: 'SavingsPlan'.
name	string	The name of the resource
properties.armSkuName	string	ARM SKU name. For example, 'Compute_Savings_Plan' for savings plan.
properties.avgUtilizationPercentage	number (decimal)	This is the average hourly utilization for each date range that corresponds to given grain (Daily, Monthly). Suppose the API call is for usageDate > 2025-03-01 and usageDate < 2022-10-31 at a daily granularity. There will be one record per benefit id for each day. For a single day, the avgUtilizationPercentage value will be equal to the average of the set of values where the set contains 24 utilization percentage entries one for each hour in a specific day.
properties.benefitId	string	The benefit ID is the identifier of the benefit.
properties.benefitOrderId	string	The benefit order ID is the identifier for a benefit purchase.
properties.benefitType	benefitKind	The benefit type. Supported values: 'SavingsPlan'.
properties.maxUtilizationPercentage	number (decimal)	This is the maximum hourly utilization for each date range that corresponds to given grain (Daily, Monthly). Suppose the API call is for usageDate > 2025-03-01 and usageDate < 2022-10-31 at a daily granularity. There will be one record per benefit id for each day. For a single day, the maxUtilizationPercentage value will be equal to the largest in the set of values where the set contains 24 utilization percentage entries one for each hour in a specific day. If on the day 2022-10-18, the largest utilization percentage was 90% at hour 5, then the value for the maxUtilizationPercentage in the response will be 90%.
properties.minUtilizationPercentage	number (decimal)	This is the minimum hourly utilization for each date range that corresponds to given grain (Daily, Monthly). Suppose the API call is for usageDate > 2025-03-01 and usageDate < 2022-10-31 at a daily granularity. There will be one record per benefit id for each day. For a single day, the minUtilizationPercentage value will be equal to the smallest in the set of values where the set contains 24 utilization percentage entries one for each hour in a specific day. If on the day 2022-10-18, the lowest utilization percentage was 10% at hour 4, then the value for the minUtilizationPercentage in the response will be 10%.
properties.usageDate	string (date-time)	Date corresponding to the utilization summary record. If the grain of data is monthly, value for this field will be first day of the month.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

Share via

Benefit Utilization Summaries - List By Savings Plan Order

URI Parameters

Responses

Security

azure_auth

Scopes

Examples

SavingsPlanUtilizationSummariesDaily

Sample request

Sample response

Definitions

benefitKind

BenefitUtilizationSummariesListResult

ErrorDetails

ErrorResponse

grainParameter

IncludedQuantityUtilizationSummary

SavingsPlanUtilizationSummary