Cloud for Sustainability API (preview) OData query examples
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).
Can you provide more information on how to use nextLink for pagination?
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.
Related information
- Cloud for Sustainability API overview
- Microsoft Cloud for Sustainability API calculation methodology
- Microsoft Cloud for Sustainability API
