Generate Benefit Utilization Summaries Report - Generate By Savings Plan Order Id

  • Reference
Service:
Cost Management
API Version:
2023-11-01

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

POST https://management.azure.com/providers/Microsoft.BillingBenefits/savingsPlanOrders/{savingsPlanOrderId}/providers/Microsoft.CostManagement/generateBenefitUtilizationSummariesReport?api-version=2023-11-01

URI Parameters

Name In Required Type Description
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.

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

GenerateUtilizationSummariesReportBySavingsPlanOrder

Sample request

POST https://management.azure.com/providers/Microsoft.BillingBenefits/savingsPlanOrders/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/generateBenefitUtilizationSummariesReport?api-version=2023-11-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.BillingBenefits/savingsPlanOrders/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/benefitUtilizationSummariesOperationResults/cf9f95c9-af6b-41dd-a622-e6f4fc60c3ee?api-version=2023-11-01
Retry-After: 60
Status code:
200 
{
  "input": {
    "grain": "Daily",
    "benefitOrderId": "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