• 2 min read

Azure ARM API for consumption usage details

As an update to the Reporting APIs for Enterprise Azure Customers we are releasing an updated usage details API that is a first step in the consolidation of Azure cost and usage based APIs in the ARM…

As an update to the Reporting APIs for Enterprise customers we are releasing an updated usage details API. This is a first step in the consolidation of Azure cost and usage based APIs in the ARM (Azure Resource Manager) model. The updated usage details API will support:

  • Migrating from a key based authorization model to ARM based authentication. The benefits of this authorization mode are an improved security posture and the ability to utilize ARM RBAC for authorization.
  • Adding support for Web Direct subscriptions, with a few exceptions documented below.
  • The ability to use filters and expand usage details.
  • Call the API for either a subscription scope, or a subscription and billing period scope. All calls for a subscription will return data for the current billing period.
  • Filter criteria will support dates, resource groups, resources, and instances. Additional details on the filters are available in the Swagger.

For Enterprise customers, reporting at a grain higher than the subscription is a work in progress and until released, you will need to continue to use the existing API. The consumption ARM API is the area we continue to invest in for cost related APIs with the goals of normalizing our APIs across the different purchase channels, starting with Enterprise customers and Web Direct. The APIs will continue to evolve as we invest in extending the APIs to include features such as budgets, and support for other subscription types and channels in upcoming releases.

Usage details API

Usage details list

The usage details API returns usage and cost information for the provided subscription. In addition, the API also supports a few options for scope, filter, and details. For an example and detailed documentation, please visit the documentation page.

At minimum you will need to have Billing Reader privileges on the subscription to call the API. Also, view charges will need to be enabled on the EA portal for EA customers.

Usage details options


The scope is the context of the subscription or the billing period that your are calling the API under. Scope can be just the subscription or a specific billing period for a subscription, as shown below.

  • Subscription only: subscriptions/{subscriptionId}
  • Billing period for a subscription: /subscriptions/{subscriptionId}/providers/Microsoft.Billing/billingPeriods/{billingPeriodName}


By default, the API only returns summarized usage information with a meter ID. If you want additional information on the meter, or additional information about the resource, you will need to add the expand parameter with the appropriate value:

  • Expanded meter information: properties/meterDetails
  • Expanded properties bag: properties/additionalProperties


Filters can be used to limit data to specific criteria. Filters are supported on only a few columns, including the date range filter, with a few limitations described in the documentation.

Limitations on subscriptions

The following subscription types are currently not supported with this API:

  • MS-AZR-0145P
  • MS-AZR-0 146P
  • MS-AZR-159P
  • MS-AZR-0036P
  • MS-AZR-0143P
  • MS-AZR-0015P
  • MS-AZR-0144P

Additional resources