Cloud for Sustainability API (Preview) overview

  • Article
  • 5 minutes to read

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 usage.

Accurate carbon accounting requires good information from partners, vendors, and suppliers. The Cloud for Sustainability APIs give you transparency on the carbon emissions generated by your usage of Azure. Microsoft’s carbon accounting extends across all three scopes of emissions with a methodology validated by Stanford University in 2018. It uses consistent and accurate carbon accounting to quantify the effect of Microsoft cloud services 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.

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 Azure accounts

Microsoft Cloud for Sustainability APIs 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 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.

Configure data sources and enable the APIs

Important

To successfully enable access to your organization's data, this step must be performed by a billing account administrator with a role as billing account reader/contributor/owner on your Azure billing account. The billing account administrator may create instances or be added to instances to enable data sources and enable the API. If you don't have permissions to access your Azure billing account data, you can explore the API using demo data only.

  1. On the Data Sources tab, toggle the connection on to connect Azure 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, you'll proceed with demo data only.

    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. .

Try the APIs

On the API Management tab, select Try API. A developer portal will open in a new tab where you can explore the request and response schemas and make live requests against the Microsoft Cloud for Sustainability APIs.

  1. 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
    • instanceId: Found in the URL of for the Microsoft Cloud for Sustainability API portal

    Try it page.

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

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.

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 are added to the application by an admin of an instance. 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.

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.

See also

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