Azure Consumption

Article
12/20/2022
4 minutes to read

The Azure Consumption APIs give you programmatic access to cost and usage data for your Azure resources. The APIs currently only support Enterprise Enrollments, Web Direct subscriptions (with a few exceptions), and CSP Azure plan subscriptions. The APIs are continually updated to support other types of Azure subscriptions.

Azure Consumption APIs provide access to:

Enterprise Customers Only
- Price sheet
- Budgets
- Forecasts
- Balances
- Tags
- Cost Tags
Enterprise and Web Direct Customers
- Reservation Details
- Reservation Summaries
- Marketplace Charges
- Usage Details
- Reservation Recommendations

List of Unsupported Subscription Types

MS-AZR-0145P (CSP)
MS-AZR-0146P (CSP)
MS-AZR-159P (CSP)
MS-AZR-0036P (sponsored)
MS-AZR-0143P (sponsored)
MS-AZR-0015P (internal)
MS-AZR-0144P (DreamSpark)

REST Operation Groups

Operation Group	Description
Budgets	Provides operations to set, update, and delete budgets at a Subscription or resource group scope. Supports cost and usage budgets.
Price Sheet	Provides operations to get price sheet for Enterprise Subscriptions.
Marketplace Charges	Provides operations to get usage information for marketplace resources on subscription or Enterprise Billing accounts.
Usage Details	Provides operations to get usage information on subscription or Enterprise Billing accounts.
Reservation Details	Provides operations to get reservation detailed usage for Pay as you go and Enterprise Subscriptions.
Reservation Details Report	Provides operations to get reservation detailed usage for Pay as you go and Enterprise Subscriptions in a report format optimized for large data sizes.
Reservation Summaries	Provides operations to get reservation summary usage for Pay as you go and Enterprise Subscriptions.
Reservation Recommendations	Provides operations to get reservation recommendations for Pay as you go and Enterprise Subscriptions.
Forecasts	Provides operations to get usage forecasts for Enterprise Subscriptions.
Balances	Provides operations to get balances and summaries for Enterprise Billing Accounts.
Tags	Provides operations to get tags info for Enterprise Subscriptions.

Working with billing periods and date ranges

Usage Details and Marketplace Charges accept billing period or date ranges for defining the start and end dates for the usage data.

Here is the API behavior based on billing periods and date ranges in request.

Billing period present in request	Start date present in request	End date present in request	API behavior
no	no	no	Data for current billing period is returned in response
no	yes	no	Data for current billing period is returned in response
no	no	yes	Data for current billing period is returned in response
no	yes	yes	Data for specified Start and End Date is returned in response
yes	no	no	Data for specified billing period is returned in response
yes	yes	no	Data for specified billing period is returned in response
yes	no	yes	Data for specified billing period is returned in response
yes	yes	yes	Data for specified Start and End Date is returned in response, supplied billing period is ignored

Maximum allowed date range is 12 months in one request and data is available from May 1, 2014 or later.

Getting list of billing periods

For providing a valid billing period in request, client should first get a list of available billing periods by subscription, using following API

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Billing/billingPeriods?api-version=2017-04-24-preview

Using this list, client can pick a specific billing period to get consumption data.

Late Arriving Data

To accommodate third party services, that have delays in reporting usage, the reported usage date is set to the time at which the usage data was sent, as opposed to when the actual usage took place that is, consumption time.

As a result, the usage will be rated for and applied to the reported time. In order to represent the actual consumption time, the properties.AdditionalProperties field will now contain two additional properties. ConsumptionBeginTime and ConsumptionEndTime are the new fields that correspond to the actual consumption time window.

These changes will result in a few scenarios that will need to be addressed when calling the usage details API:

Month End Reporting: For usage that occurred during a month, but reported during the next month, customers will need to look at the additionalProperties field to assign the usage, to the appropriate month.
Query Usage details: When querying the usage details API by a date range, the query only applies to usage report date and not the consumption time in the additionalProperties field. For customers looking to map usage details to invoices, this update does not affect the process as the invoice will process the usage based on the usage report date. For customers, looking to map usage details to a specific calendar date/month, this update is a breaking change and for these scenarios the usage report date cannot be used and the date that the usage occurred, in the additionalProperties section must be used.

Sample Call for Additional Details:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Consumption/usageDetails?api-version=2018-03-31&$expand=properties/additionalProperties

Sample Response snippet:

  "properties": {
    "billingPeriodId":"/subscriptions/{subscriptionid}/providers/Microsoft.Billing/billingPeriods/20180501",
    "usageStart":"2018-05-01T00:00:00.0000000Z",
    "usageEnd":"2018-05-01T23:59:59.0000000Z",
    "instanceId":"/subscriptions/{subscriptionid}/resourceGroups/{resourcegroup}/providers/Microsoft.Cdn/profiles/{profile}",
    "instanceName":"{id}",
    "instanceLocation":"SouthCentralUS",
    "meterId":"6b88ada0-cbc0-4874-be0e-23004f8b4de7",
    "usageQuantity":0.002065,
    "pretaxCost":0,
    "currency":"USD",
    "additionalProperties": {
      "Provider": "1",
      "ConsumptionBeginTime": "2018-05-01T19:00:00",
      "ConsumptionEndTime": "2018-05-01T20:00:00"
    }
  }