Generate Benefit Utilization Summaries Report - Generate By Savings Plan Id

Reference

Service:: Cost Management

API Version:: 2024-08-01

Triggers generation of a benefit utilization summaries report for the provided savings plan.

POST https://management.azure.com/providers/Microsoft.BillingBenefits/savingsPlanOrders/{savingsPlanOrderId}/savingsPlans/{savingsPlanId}/providers/Microsoft.CostManagement/generateBenefitUtilizationSummariesReport?api-version=2024-08-01

URI Parameters

Name	In	Required	Type	Description
savingsPlanId	path	True	string	Savings plan ID.
savingsPlanOrderId	path	True	string	Savings plan order ID.
api-version	query	True	string	The API version to use for this operation.

Request Body

Name	Required	Type	Description
endDate	True	string	The end date of the summaries data that will be served in the report.
grain	True	grain	The grain the summaries data is served at in the report. Accepted values are 'Daily' or 'Monthly'.
startDate	True	string	The start date of the summaries data that will be served in the report.
benefitId		string	Benefit id the benefit utilization summaries report is for. Required for benefit id scope. Not supported for benefit order or any billing scopes.
benefitOrderId		string	Benefit order id the benefit utilization summaries report is for. Required for benefit order and benefit id scopes. Not supported for any billing scopes.
billingAccountId		string	Billing account the benefit utilization summaries report is for. Required for billing account and billing profile scopes. Not supported for any benefit scopes.
billingProfileId		string	Billing profile id the benefit utilization summaries report is for. Required for billing profile scope. Not supported for billing account or any benefit scopes.
kind		benefitKind	The type of benefit data requested. Required for billing account and billing profile scopes. Implied and not to be passed at benefit scopes. Supported values are Reservation and SavingsPlan

Responses

Name	Type	Description
200 OK	BenefitUtilizationSummariesOperationStatus	The status of the generation of the benefit utilization summaries report. This could be in progress, failed, or completed.
202 Accepted		Accepted. Request will be processed. Use the location header to check the status. Headers Location: string Retry-After: integer
Other Status Codes	ErrorResponse	Error response describing why the operation failed.

Name

Type

Description

200 OK

BenefitUtilizationSummariesOperationStatus

The status of the generation of the benefit utilization summaries report. This could be in progress, failed, or completed.

202 Accepted

Accepted. Request will be processed. Use the location header to check the status.

Headers

Location: string
Retry-After: integer

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

GenerateUtilizationSummariesReportBySavingsPlan

Sample request

HTTP

POST https://management.azure.com/providers/Microsoft.BillingBenefits/savingsPlanOrders/00000000-0000-0000-0000-000000000000/savingsPlans/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/generateBenefitUtilizationSummariesReport?api-version=2024-08-01

{
  "endDate": "2022-08-31T00:00:00Z",
  "startDate": "2022-06-01T00:00:00Z",
  "grain": "Daily"
}

Sample response

Status code:: 202

Location: https://management.azure.com/providers/Microsoft.Capacity/savingsPlanOrders/00000000-0000-0000-0000-000000000000/savingsPlans/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/benefitUtilizationSummariesOperationResults/cf9f95c9-af6b-41dd-a622-e6f4fc60c3ee?api-version=2024-08-01
Retry-After: 60

Status code:: 200

{
  "input": {
    "grain": "Daily",
    "benefitOrderId": "00000000-0000-0000-0000-000000000000",
    "benefitId": "00000000-0000-0000-0000-000000000000",
    "kind": "SavingsPlan",
    "endDate": "2022-08-31T00:00:00Z",
    "startDate": "2022-06-01T00:00:00Z"
  },
  "status": "Complete",
  "properties": {
    "reportUrl": "https://storage.blob.core.windows.net/details/20220611/00000000-0000-0000-0000-000000000000?sv=2016-05-31&sr=b&sig=jep8HT2aphfUkyERRZa5LRfd9RPzjXbzB%2F9TNiQ",
    "secondaryReportUrl": "https://storage-secondary.blob.core.windows.net/details/20220611/00000000-0000-0000-0000-000000000000?sv=2016-05-31&sr=b&sig=jep8HT2aphfUkyERRZa5LRfd9RPzjXbzB%2F9TNiQ",
    "validUntil": "2022-06-12T02:56:55.5021869Z"
  }
}

Definitions

Name	Description
AsyncOperationStatusProperties	Object representing the report url and valid until date of the async report generated.
benefitKind	Reservation or SavingsPlan.
BenefitUtilizationSummariesOperationStatus	Status of a benefit utilization summaries report. Provides Async Benefit Utilization Summaries Request input, status, and report sas url.
BenefitUtilizationSummariesRequest	Properties of an async benefit utilization summaries request.
BenefitUtilizationSummaryReportSchema	The CSV file from the reportUrl and secondaryReportUrl blob link will consist of the following columns of benefit utilization data. UtilizedPercentage will be 0 for savings plans reports and non data bricks reservations. Utilization percentages will be 0 for data bricks reservations.
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.
grain	The grain of the usage. Supported values: 'Hourly'
OperationStatusType	The status of the creation of the benefit utilization summaries report.

AsyncOperationStatusProperties

Object representing the report url and valid until date of the async report generated.

Name	Type	Description
reportUrl	BenefitUtilizationSummaryReportSchema	Sas url to the async benefit utilization summaries report. Will be empty if the report is in Running or Failed state.
secondaryReportUrl	BenefitUtilizationSummaryReportSchema	Sas url to async benefit utilization summaries report in secondary storage in case of primary outage. Will be empty if the report is in Running or Failed state.
validUntil	string	The date that the sas url provided in reportUrl expires.

benefitKind

Reservation or SavingsPlan.

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

BenefitUtilizationSummariesOperationStatus

Status of a benefit utilization summaries report. Provides Async Benefit Utilization Summaries Request input, status, and report sas url.

Name	Type	Description
input	BenefitUtilizationSummariesRequest	Input given to create the benefit utilization summaries report.
properties	AsyncOperationStatusProperties	Contains sas url to the async benefit utilization summaries report and a date that the url is valid until. These values will be empty if the report is in a Running or Failed state
status	OperationStatusType	The status of the creation of the benefit utilization summaries report.

BenefitUtilizationSummariesRequest

Properties of an async benefit utilization summaries request.

Name	Type	Description
benefitId	string	Benefit id the benefit utilization summaries report is for. Required for benefit id scope. Not supported for benefit order or any billing scopes.
benefitOrderId	string	Benefit order id the benefit utilization summaries report is for. Required for benefit order and benefit id scopes. Not supported for any billing scopes.
billingAccountId	string	Billing account the benefit utilization summaries report is for. Required for billing account and billing profile scopes. Not supported for any benefit scopes.
billingProfileId	string	Billing profile id the benefit utilization summaries report is for. Required for billing profile scope. Not supported for billing account or any benefit scopes.
endDate	string	The end date of the summaries data that will be served in the report.
grain	grain	The grain the summaries data is served at in the report. Accepted values are 'Daily' or 'Monthly'.
kind	benefitKind	The type of benefit data requested. Required for billing account and billing profile scopes. Implied and not to be passed at benefit scopes. Supported values are Reservation and SavingsPlan
startDate	string	The start date of the summaries data that will be served in the report.

BenefitUtilizationSummaryReportSchema

The CSV file from the reportUrl and secondaryReportUrl blob link will consist of the following columns of benefit utilization data. UtilizedPercentage will be 0 for savings plans reports and non data bricks reservations. Utilization percentages will be 0 for data bricks reservations.

Name	Type	Description
AvgUtilizationPercentage	string
BenefitId	string
BenefitOrderId	string
BenefitType	string
Kind	string
MaxUtilizationPercentage	string
MinUtilizationPercentage	string
UsageDate	string
UtilizedPercentage	string

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.

grain

The grain of the usage. Supported values: 'Hourly'

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.

OperationStatusType

The status of the creation of the benefit utilization summaries report.

Name	Type	Description
Complete	string
Failed	string
Running	string

Share via

Generate Benefit Utilization Summaries Report - Generate By Savings Plan Id

URI Parameters

Request Body

Responses

Security

azure_auth

Scopes

Examples

GenerateUtilizationSummariesReportBySavingsPlan

Sample request

Sample response

Definitions

AsyncOperationStatusProperties

benefitKind

BenefitUtilizationSummariesOperationStatus

BenefitUtilizationSummariesRequest

BenefitUtilizationSummaryReportSchema

ErrorDetails

ErrorResponse

grain

OperationStatusType

Additional resources