Cloud for Sustainability API (Preview) overview

  • Article

Important

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

Microsoft Cloud for Sustainability provides APIs to access emissions data related to your Azure and Microsoft 365 usage.

Accurate carbon accounting requires good information from partners, vendors, and suppliers. The Cloud for Sustainability APIs gives you transparency on the carbon emissions generated by your usage of Azure and Microsoft 365. Microsoft’s carbon accounting extends across all three scopes of emissions with a third party-validated methodology. It uses consistent and accurate carbon accounting to quantify the effect of Azure and Microsoft 365 on customers’ environmental footprint.

Details of the API are listed in the Microsoft Cloud for Sustainability API reference. They include additional information about operations, parameters, and responses.

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. This preview isn't intended for legal compliance, marketing, or reporting purposes.

Get started with Cloud for Sustainability APIs

Note

If your organization would like to gain access to the Microsoft Cloud for Sustainability API (Preview), submit this sign up form.

Get started with the APIs with the following procedures:

Supported accounts

  • Azure: Microsoft Cloud for Sustainability APIs for Azure support EA Direct, MCA, and MPA accounts with direct billing relationships with Microsoft. Customers who purchase Azure from a Cloud Solution Provider (CSP) aren't supported and must work directly with their CSP to learn about their cloud emissions. Legacy accounts, credits-based accounts, China enrollments, and Azure Government accounts aren't supported. To check your account type, go to Check the type of your account.

    Note

    Azure Hybrid Benefit usage isn't currently captured or reflected in the emissions.

  • Microsoft 365: Microsoft Cloud for Sustainability APIs for Microsoft 365 support business, enterprise, or education subscriptions for Microsoft 365 or Office 365. National/regional cloud deployments including but not limited to Microsoft's US Government clouds and Office 365 operated by 21Vianet aren't supported.

Sign in and create an instance

After you receive access to the Microsoft Cloud for Sustainability APIs from Microsoft, sign in with your Azure Active Directory (Azure AD) credentials.

You must create an instance to access the Microsoft Cloud for Sustainability APIs. By creating the instance, you become the administrator of that instance. The administrator of the instance can add users, groups, and applications to the instance.

Watch this video for an overview of using Cloud for Sustainability APIs and portal:

Configure data sources and enable the APIs

Important

To successfully enable access to your organization's data, this step must be performed by the relevant administrator. For Azure MCA accounts, a billing account administrator with a role as billing account reader, contributor, or owner is required. For Azure EA accounts, an enterprise administrator or enterprise administrator - read-only is required. Check your role in Azure portal. For Microsoft 365, one of the following roles is required: Global admin, Exchange admin, Skype for Business admin, SharePoint admin, Global reader, Report reader. The Azure and Microsoft 365 administrators may create instances or be added to instances to enable data sources and enable the API. If you don't have a required admin role to enable the data, you can explore the API using demo data only.

  1. On the Data Sources tab, toggle the connection on to connect Azure or Microsoft 365 emissions data. Ensure the status is listed as Available before using the APIs. This action enables emissions data related to all enrollments or billing accounts for which you have access. If you don't have access to any emissions data, proceed with demo data only.

    Note

    It may take up to 48 hours for Microsoft 365 emissions data to become available after enabling the data source. Disabling the Microsoft 365 data source will permanently delete historic Microsoft 365 emissions data.

    Data sources.

  2. Select the API Management tab, and then select Enable.

    Enabling the API generates primary and secondary API keys for your instance to use in API requests. To regenerate the keys, select Refresh icon. . To copy keys, select Copy icon. .

Interested in configuring an app to call the Cloud for Sustainability API? Watch this demo:

Try the APIs

On the API Management tab, select Try API to explore OData and Export APIs. Interactively query your emissions data by connecting low-latency OData APIs to your dashboards. Or, do your own bulk processing by transferring your emissions data directly to your Azure Data Lake Storage using Export APIs. A developer portal opens in a new tab where you can explore the request and response schemas and make live requests against the Microsoft Cloud for Sustainability APIs.

Try OData APIs

  1. On the left navigation, ensure Group by tag is enabled and select the OData grouping to review the Azure and Microsoft 365 OData APIs.

  2. To make a live request, select Try it. Enter all required fields:

    • Authorization: Automatically populated authorization token
    • Subscription key: Automatically populated with the API key from the API Management tab
    • enrollmentId: Your enrollment ID, also known as billing account ID. Azure only. If you don't have access to an enrollment, you can explore the API using demo data by entering demodata in this field.
    • instanceId: Found in the URL of for the Microsoft Cloud for Sustainability API portal
    • tenantId: Microsoft 365 tenant ID.

    Try it page.

  3. Add all necessary query parameters. Scroll to the bottom of the side pane and select Send. The HTTP response displays at the bottom of the pane.

Watch this video to learn more about Cloud for Sustainability APIs with OData:

Try Export APIs

  1. On the left navigation, ensure Group by tag is enabled and select the Export grouping to begin exporting emissions and usage data to your data lake. Select RunExportJob.

  2. Select Try it. Enter all required fields and select Send.

    • Authorization: Automatically populated authorization token
    • Subscription key: Automatically populated with the API key from the API Management tab
    • instanceId: Found in the URL of for the Microsoft Cloud for Sustainability API portal
    • exportJobType: Select Azure or Microsoft 365 to designate the data source for emissions and usage data to export.
    • demodata: Input "true" if you would like to explore this functionality by exporting demo data.

  3. After you select Send, scroll down to see the HTTP response. If you're exporting Azure data, the response lists the enrollment IDs for the exported data. If you don't have access to Azure or Microsoft 365 data, this operation doesn't succeed. Ensure you've properly configured your data sources.

    Initially, the response indicates the job has NotStarted. The export job takes 2-3 minutes to complete, and you can use the jobID to check the status of the export using the ExportJobStatus API. Ensure the job has succeeded, which indicates that the exported data is now available in the staging blob storage.

    You can use LatestExportJob to review information regarding your last export job.

    You can use ExportJobs API to review information regarding your historical exports.

  4. Use the ExportLocation API to obtain the SAS URL. The SAS URL will expire after two hours. Copy the SAS URL to access the exported data from the staging blob storage.

  5. The data is set to expire 28 days after the export job is run and must be copied before the expiry. Otherwise, the data is deleted from the staging location. Users may rerun an export job at any time to gain another batch of data with a 28 day expiry and including the most recent data set. There are a few ways to access the exported data.

    1. Azure Storage Explorer

      Install and open Azure Storage Explorer. Select Open Connect Dialog button and then select ADLS Gen2 container or directory. Select Shared access signature URL (SAS) and paste the SAS URL from step 4 into Blob container or directory SAS URL input. Select Next and then select Connect. You need to locate or create a container in a new or existing storage account to use for storing this exported data. Copy the Azure or Microsoft 365 data from the staging blob storage and paste into the container of your choice.

    2. Use azcopy. Using the SAS URL from step 4 and the URL for the storage account where you're storing your exported emissions (destination URL), run the azcopy.exe command:

      • azcopy login
      • azcopy list <SAS URL>
      • azcopy cp <SAS URL> <destination URL>

    3. Spark script

      Use mssparkutils in Microsoft Fabric or Synapse. You can choose to use alternative libraries and environments.

      import subprocess
from notebookutils import mssparkutils

result = subprocess.run(['pip', 'install', 'azure-storage-blob'], capture_output=True)

# replace with SAS URI from API request
source_sas_url = 'https://<account_name>.blob.windows.net/<container_name>/<path>?<sas_token>'

start_index = source_sas_url.find('https://') + len('https://')
end_index = source_sas_url.find('.blob', start_index)
account_name = source_sas_url[start_index:end_index]
split = source_sas_url.split('?', 1)
domain_path = split[0]
sas_token = split[1]
container_name = domain_path.split('/')[3]

source_mount_point = '/src'
destination_mount_point = '/dest'

mssparkutils.fs.unmount(source_mount_point)
mssparkutils.fs.mount(
    f'abfss://{container_name}@{account_name}.blob.core.windows.net',
    source_mount_point,
    { 'sasToken': sas_token })

mssparkutils.fs.unmount(destination_mount_point)
mssparkutils.fs.mount( 
    'abfss://<destinationPath>', # replace with destination connection string
    destination_mount_point)

mssparkutils.fs.cp(src_path, dest_path, True)

Sample queries

For a short list of OData sample queries to work with the APIs, go to OData query examples.

Assign permissions

Access to Microsoft Cloud for Sustainability APIs is restricted to users in your organization that an admin of an instance adds to the application. A user can be a single user, group, or application. Guest accounts aren't supported. There are three types of roles that may be assigned:

  • Viewer: Can view all pages within the Microsoft Cloud for Sustainability API.
  • Contributor: Can interact with all pages in the Microsoft Cloud for Sustainability API portal. Can't add or remove users.
  • Admin: All permissions available, including the ability to add or remove users.

Note

Contributors and admins can't disable or enable the Microsoft 365 data source unless they are Global admin, Exchange admin, Skype for Business admin, SharePoint admin, Global reader, or Report reader.

To add users, groups, or apps as an admin:

  1. Select the Permissions tab, and then select Add Users.
  2. Use the Search field to find the Azure AD user, application, or group you want to add.
  3. Select a role assignment, and then select Save.

Manage instances

Navigate to the instance icon Instance icon to find a list of all instances, create instances, or remove instances.

View API usage

View details about your real-time API usage.

  1. Navigate to the API Management tab, and then select Usage.
  2. Select a time frame to view.

The API usage page contains three sections:

  • API calls: A chart that visualizes the aggregated number of calls to the API in the selected time frame.
  • Data transfer: A chart that shows the amount of data that was transferred through the API in the selected time frame.
  • Operations: A table with rows for each available API operation and details about the usage of the operations.

FAQ

How does Microsoft calculate cloud carbon emissions made available by the API?

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

Where can I learn more about writing queries with OData?

To learn more about OData, go to Query options overview.

Where is the data used to produce this report stored?

The data is stored in the United States.

Why can't I see emissions data for the previous month?

Emissions data for a given month will be available by the 14th day after the end of that month (including nonbusiness days).

I'm unable to create an instance. Why?

You may be trying to access the Cloud for Sustainability API portal with an account that's associated with a different host tenant ID than the one provided on the onboarding form. This situation can occur when you use a guest account. Guest accounts aren't supported. If you would like us to onboard another tenant, resubmit the onboarding form.

I have a different tenant ID for Microsoft 365 and Azure. Can I still use the Microsoft Cloud for Sustainability API?

You can still access the APIs, but the portal doesn't support multiple tenants per instance. You need to onboard these tenants to the APIs separately.

How do I configure an app to call the Microsoft Cloud for Sustainability API?

Interested in configuring an app to call the Cloud for Sustainability API? Watch this demo:

On Azure portal, go to your Azure Active Directory, select App registrations and then on + New registration. In the new registration page, give a name for your app registration, customize options to your needs, and then select Register. Go to the Azure AD page, select the Enterprise applications blade, set Application type to be Microsoft Applications, and search by application name MCFS SDS. The ApplicationId parameter you passed in the New-AzADServicePrincipal command required during onboarding is the ApplicationId of the Microsoft Cloud for Sustainability API (c3163bf1-092f-436b-b260-7ade5973e5b9) with which you created an instance (enterprise application) of the Microsoft Cloud for Sustainability API app registration in your own tenant.

With that in place, you can now go to your app registration page and select API permissions blade. To add permission for your app registration to be able to call the Microsoft Cloud for Sustainability API, select + Add a permission, followed by the APIs my organization uses option. Then, search the ApplicationId of the Microsoft Cloud for Sustainability API (c3163bf1-092f-436b-b260-7ade5973e5b9), select MCFS SDS, and then select the App.Emissions.Read permission of the Application permissions blade.

This application type permission needs to be given admin consent by selecting Grant admin consent for {your-tenant}.

Lastly, visit the Microsoft Cloud for Sustainability API homepage, navigate to the Permissions blade, then select + Add. In the side panel that appears, choose Viewer as the Role in the User, Group or Application input and proceed to search for your application registration. Select Save.

I'm obtaining an access token for my application, what is the resource URL?

c3163bf1-092f-436b-b260-7ade5973e5b9/.default

How much historic data is available?

  • Azure: The usage and emissions data covers the last five years of data associated with the enrollment.
  • Microsoft 365: Emissions data cover the last 12 months of data associated with the Microsoft 365 subscription.

Disclaimer

The Microsoft Cloud for Sustainability API (preview) is based on industry standards for carbon calculation of servers and provides general estimates to help organizations gain insights into the carbon emissions of the IT infrastructure associated with the use of Azure cloud services. The findings, interpretations, and conclusions presented with the Microsoft Cloud for Sustainability API (preview), including the calculations, aren't specific advice or recommendations. Information and views expressed may change without notice. The Microsoft Cloud for Sustainability API (preview) is provided as is, without any representation or warranty of any kind, either expressed or implied, including without limitation any representations or endorsements regarding the use of, the results of, or performance of the Microsoft Cloud for Sustainability API (preview), its appropriateness, accuracy, reliability, or correctness. The entire risk as to the use of the Microsoft Cloud for Sustainability API (preview) is assumed by you. Microsoft does not assume liability for the use of the Microsoft Cloud for Sustainability API (preview). In no event will Microsoft be liable for additional direct or indirect to damages including any lost profits, lost savings, or any incidental or consequential damages arising from any defects, or the use or inability to use the Microsoft Cloud for Sustainability API (preview), even if Microsoft has been advised of the possibility of such damages.

See also

Microsoft Cloud for Sustainability API OData query examples
Microsoft Cloud for Sustainability API calculation methodology
Microsoft Cloud for Sustainability API