Share via

Generate Benefit Utilization Summaries Report - Generate By Reservation Id

Service:
Cost Management
API Version:
2025-03-01

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

POST https://management.azure.com/providers/Microsoft.Capacity/reservationorders/{reservationOrderId}/reservations/{reservationId}/providers/Microsoft.CostManagement/generateBenefitUtilizationSummariesReport?api-version=2025-03-01

URI Parameters

Name In Required Type Description
reservationId
 path True

string

Reservation ID
reservationOrderId
 path True

string

Reservation Order ID
api-version
 query True

string

minLength: 1

The API version to use for this operation.

Request Body

Name Required Type Description
endDate True

string (date-time)

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 (date-time)

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

GenerateUtilizationSummariesReportByReservation

Sample request

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

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 (date-time)

The date that the sas url provided in reportUrl expires.

benefitKind

Enumeration

Reservation or SavingsPlan.

Value Description
IncludedQuantity

Benefit is IncludedQuantity.
Reservation

Benefit is Reservation.
SavingsPlan

Benefit is SavingsPlan.

BenefitUtilizationSummariesOperationStatus

Object

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

Object

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 (date-time)

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 (date-time)

The start date of the summaries data that will be served in the report.

BenefitUtilizationSummaryReportSchema

Enumeration

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.

Value Description
Kind
AvgUtilizationPercentage
BenefitOrderId
BenefitId
BenefitType
MaxUtilizationPercentage
MinUtilizationPercentage
UsageDate
UtilizedPercentage

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.

grain

Enumeration

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

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.

OperationStatusType

Enumeration

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

Value Description
Running
Complete
Failed