Benefit Utilization Summaries - List By Billing Account Id

Reference

Service:: Cost Management

API Version:: 2023-11-01

Lists savings plan utilization summaries for the enterprise agreement scope. Supported at grain values: 'Daily' and 'Monthly'.

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.CostManagement/benefitUtilizationSummaries?api-version=2023-11-01

With optional parameters:

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.CostManagement/benefitUtilizationSummaries?api-version=2023-11-01&grainParameter={grainParameter}&filter={filter}

URI Parameters

Name	In	Required	Type	Description
billingAccountId	path	True	string	Billing account ID
api-version	query	True	string	The API version to use for this operation.
filter	query		string	Supports filtering by properties/benefitId, properties/benefitOrderId and 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

SavingsPlanUtilizationSummaries-BillingAccount

Sample Request

HTTP

GET https://management.azure.com/providers/Microsoft.Billing/billingAccounts/12345/providers/Microsoft.CostManagement/benefitUtilizationSummaries?api-version=2023-11-01&filter=properties/usageDate ge 2022-10-15 and properties/usageDate le 2022-10-18

Sample Response

Status code:: 200

{
  "value": [
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/12345/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"
      }
    },
    {
      "id": "/providers/Microsoft.Billing/billingAccounts/12345/providers/Microsoft.CostManagement/benefitUtilizationSummaries/88cccc88-8ccc-8c88-888c-88cc8c8c88c8_444d44dd-d4d4-4dd4-444d-4dd4444ddddd_20211117",
      "kind": "SavingsPlan",
      "name": "88cccc88-8ccc-8c88-888c-88cc8c8c88c8_444d44dd-d4d4-4dd4-444d-4dd4444ddddd_20211117",
      "type": "Microsoft.CostManagement/benefitUtilizationSummaries",
      "properties": {
        "armSkuName": "Compute_Savings_Plan",
        "avgUtilizationPercentage": 60,
        "benefitOrderId": "/providers/Microsoft.BillingBenefits/savingsPlanOrders/88cccc88-8ccc-8c88-888c-88cc8c8c88c8",
        "benefitId": "/providers/Microsoft.BillingBenefits/savingsPlanOrders/88cccc88-8ccc-8c88-888c-88cc8c8c88c8/savingsPlans/444d44dd-d4d4-4dd4-444d-4dd4444ddddd",
        "benefitType": "SavingsPlan",
        "maxUtilizationPercentage": 70,
        "minUtilizationPercentage": 50,
        "usageDate": "2022-10-17T00: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

Reservation or SavingsPlan.

Name	Type	Description
IncludedQuantity	string	Benefit is IncludedQuantity.
Reservation	string	Benefit is Reservation.
SavingsPlan	string	Benefit is SavingsPlan.

BenefitUtilizationSummariesListResult

List of benefit utilization summaries.

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

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.

Name	Type	Description
error	ErrorDetails	The details of the error.

grainParameter

Grain.

Name	Type	Description
Daily	string	Hourly grain corresponds to value per day.
Hourly	string	Hourly grain corresponds to value per hour.
Monthly	string	Hourly grain corresponds to value per month.

IncludedQuantityUtilizationSummary

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 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	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

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	This is the average hourly utilization for each date range that corresponds to given grain (Daily, Monthly). Suppose the API call is for usageDate > 2023-11-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	This is the maximum hourly utilization for each date range that corresponds to given grain (Daily, Monthly). Suppose the API call is for usageDate > 2023-11-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	This is the minimum hourly utilization for each date range that corresponds to given grain (Daily, Monthly). Suppose the API call is for usageDate > 2023-11-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 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"