Share via

Cloud for Sustainability API (preview) OData query examples

  • Article

Free trial

Important

Some or all of this functionality is available as part of a preview release. The content and the functionality are subject to change.

Open Data Protocol (OData) is a data access protocol built on core protocols like HTTP. It uses commonly accepted methodologies like REST for the web. You can use various libraries and tools to consume OData services.

To help you build your own implementations based on the Microsoft Cloud for Sustainability API, you can review some of these frequently requested example queries.

Modify the query samples to make them work on your target environments:

  • {serviceRoot}: https://api.mcfs.microsoft.com/api/v1.0/instances/{instanceId}

  • {instanceId}: The GUID of the Cloud for Sustainability environment you want to query, such as 20aec369-f1c8-4814-a89d-4d449dd7e8a1.

  • {serviceRootM365}: {serviceRoot}/m365

  • {serviceRootAzure}: {serviceRoot}/enrollments/{enrollmentId}

  • {enrollmentId}: The enrollment ID, also known as billing account ID. Example: 12345678.

  • {tenantId}: Microsoft 365 tenant ID.

Note

Some API queries will contain many results and be split over multiple pages. The API returns a maximum of 1000 results per page. If more results are available, the API returns an @odata.nextLink property containing a URL to the next page of results.

EnrollmentEmission entity (for Azure emissions)

Represents the emissions data for a billing account, also called an enrollment.

Property Type Notes
dateKey int32 Date in yyyymmdd format; dd is always 01.
enrollmentId string Also known as billing account ID.
orgName string Same as TP Name or Top Parent Name.
subscriptionId string ID of the subscription.
subscriptionName string Name of the subscription.
azureServiceName string Name of an Azure service, for example, App Service
subService string For example, Azure Storage or Azure Compute.
azureRegionName string Azure region where the service is deployed.
scope string Greenhouse gas scope, for example, scope 1, scope 2, or scope 3.
scopeId int32 ID of the scope.
totalEmissions double Total emissions for the record (mtCO2e).

Sample queries for the EnrollmentEmission entity (for Azure emissions)

Query type Example
Emissions by enrollment {serviceRootAzure}/emissions
Select certain fields {serviceRootAzure}/emissions?$select=enrollmentId,totalEmissions,scopeId
Include count {serviceRootAzure}/emissions?$count=true
Limit result count {serviceRootAzure}/emissions?$top=100
Paging {serviceRootAzure}/emissions?$skip=100&$top=50
Filter by scope {serviceRootAzure}/emissions?$filter=ScopeId eq 1
Filter and aggregate {serviceRootAzure}/emissions?$apply=filter(ScopeId eq 1)/aggregate($count as Count, totalEmissions with average as Average, totalEmissions with sum as Sum)
Filter and group {serviceRootAzure}/emissions?$apply=filter(totalEmissions gt 0.05)/groupby((ScopeId), aggregate($count as Count))`

Microsoft365Emission entity (for Microsoft 365 emissions)

Represents Microsoft 365 datacenter emissions associated with the following applications:

  • Exchange Online
  • SharePoint
  • OneDrive
  • Microsoft Teams
  • Word
  • Excel
  • PowerPoint
  • Outlook
Property Type Notes
dateKey int32 Date in yyyymmdd format; dd is always 01.
tenantId string ID of the tenant.
tenantName string Name of the tenant.
officeRegionName string Microsoft 365 datacenter region.
scope string Greenhouse gas scope, for example, scope 1, scope 2, or scope 3.
totalEmissions double Total emissions for the record (mtCO2e).

Sample queries for the Microsoft365Emission entity (for Microsoft 365 emissions)

Query type Example
Emissions for tenant {serviceRootM365}/tenantemissions
Select certain fields {serviceRootM365}/emissions?$select=tenantId,totalEmissions,scope
Include count {serviceRootM365}/tenantemissions?$count=true
Limit result count {serviceRootM365}/tenantemissions?$top=100
Paging {serviceRootM365}/tenantemissions?$skip=100&$top=50
Filter by scope {serviceRootM365}/tenantemissions?$filter=Scope eq 'FILLMEIN'
Filter and aggregate {serviceRootserviceRootM365Azure}/tenantemissions?$apply=filter(scope eq 'FILLMEIN')/aggregate($count as Count, totalEmissions with average as Average, totalEmissions with sum as Sum)
Filter and group {serviceRootM365}/tenantemissions?$apply=filter(totalEmissions gt 0.05)/groupby((Scope), aggregate($count as Count))`

EnrollmentUsage entity (for Azure emissions)

Represents a calculated usage factor of Microsoft cloud resources.

Property Type Notes
dateKey int32 Date in yyyymmdd format; dd is always 01.
enrollmentId string Also known as billing account ID.
orgName string Same as TP Name or Top Parent Name.
subscriptionId string ID of the subscription.
subscriptionName string Name of the subscription.
subService string For example, Azure Storage or Azure Compute.
azureRegionName string Azure region where the service is deployed.
usage double Total usage of the record. Doesn't have the unit because it represents normalized usage of the service in the specified region.

For more information about Microsoft's calculation methodology, go to Microsoft Cloud for Sustainability API calculation methodology.|

Sample queries for the EnrollmentUsage entity

Query type Example Note
All usage data {serviceRootAzure}/usage
Total usage by month per subscription {serviceRootAzure}/usage?$apply=groupby((SubscriptionName,DateKey),aggregate(usage with sum as TotalUsage))&$orderby=SubscriptionName,DateKey

EnrollmentProjection entity (for Azure emissions)

Represents projected emissions for the remainder of the calendar year, based on a rolling average of the previous five months. Intended for annualized visualizations.

Property Type Notes
dateKey int32 Date in yyyymmdd format; dd is always 01.
enrollmentId string Also known as billing account ID.
actualEmissions double Only included for past dates (mtCO2e).
projectedEmissions double Based on a rolling average of the previous five months or less based on the actual data available for the current year (mtCO2e).
actualUsage double Only included for past dates.
projectedUsage double Based on a rolling average of the previous five months or less based on the actual data available for the current year.

Sample queries for the EnrollmentProjection entity (for Azure emissions)

Query type Example Note
Projections past 7-2022 {serviceRootAzure}/projections?$filter=dateKey gt 20220701
All projections for year {serviceRootAzure}/projections

Important

The Microsoft Cloud for Sustainability API is currently in preview and is subject to change. Your historical emissions figures may also be updated as Microsoft makes improvements to data accuracy and completeness.

FAQ

How does Microsoft calculate emissions and usage?

For information about Microsoft's calculation methodology, go to Microsoft Cloud for Sustainability API calculation methodology.

What is Rownum?

The API uses rownum for consistent pagination. The value is subject to change so your application shouldn't have a dependency on it.

What is an enrollment ID?

An enrollment ID refers to a billing account ID. Find your enrollment ID and billing account ID in the Azure portal.

How do I obtain an authorization token for my target environment?

The API requires an OAuth authorization token. We recommend using the Microsoft Authentication Library (MSAL).

The API returns an @odata.nextLink property if there are more results than returned in the current response. Your app should perform another GET on this nextLink to get the next page of results. The last page doesn't contain a nextLink. Explore this code sample for more details on pagination with an OData client library.

📄 Product page
🎓 Training

✅ Free trial
🎥 YouTube channel

💻 Community
LinkedIn icon. LinkedIn group