Export emissions data using the REST API
To export emissions data using the REST API, you must create and authorize a service principal to access your emissions data. You can then use the service principal to get an authorization token and then export emissions data using the REST API.
Create and authorize a service principal to export emissions data
A service principal is an application whose tokens can be used to authenticate and grant access to specific Azure resources by using Microsoft Entra ID (formerly Azure Active Directory). Resources include user apps, services, or automation tools.
Create a Microsoft Entra application and service principal that can access resources.
Save the tenant ID, new client ID, and client secret value for your app for use in token requests.
The app must be assigned the Carbon Optimization Reader role for the resources that you want to export emissions data for. If you plan to use the app to export emissions data for many resources, you can assign the role at the resource group or subscription level. For more information, see Assign Azure roles by using the Azure portal.
Get an authorization token
Send the following request in the command prompt or by using a client like Postman.
curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://management.azure.com'
The response body appears:
{
"token_type": "Bearer",
"expires_in": "86399",
"ext_expires_in": "86399",
"expires_on": "1672826207",
"not_before": "1672739507",
"resource": "https://management.azure.com",
"access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}
Use the access token from the response for use in the following HTTP requests.
Export emissions data using the REST API
POST /providers/Microsoft.Carbon/carbonEmissionReports?api-version=2023-04-01-preview
Host: management.azure.com
Content-Type: application/json
Authorization: Bearer <token value>
Example request
POST /providers/Microsoft.Carbon/carbonEmissionReports?api-version=2023-04-01-preview
Host: management.azure.com
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKJ...gVBNrsvg
{
"reportType": "OverallSummaryReport",
"subscriptionList": [
"abcd1234-a1b2-d3c4-e3f5-976543210abc"
],
"carbonScopeList": [
"Scope1",
"Scope2",
"Scope3"
],
"dateRange": {
"start": "2023-12-01",
"end": "2023-12-01"
}
}
curl example:
curl --location 'https://management.azure.com/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2023-04-01-preview' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXA...2-KgVBNrsvg' \
--data '{
"reportType": "OverallSummaryReport",
"subscriptionList": [
"abcd1234-a1b2-d3c4-e3f5-976543210abc"
],
"carbonScopeList": [
"Scope1",
"Scope2",
"Scope3"
],
"dateRange": {
"start": "2023-12-01",
"end": "2023-12-01"
}
}
'
Sample output
{
"value": [
{
"dataType": "OverallSummaryData",
"totalCarbonEmission": 7000.622265493289,
"totalCarbonEmission12MonthsAgo": 0,
"totalCarbonEmissionLastMonth": 7480.374908590786,
"changeRatioFor12Months": 0,
"changeRatioForLastMonth": -0.06413483935765417,
"changeValueMonthOverMonth": 0
}
]
}
Report types
| Report type |
Description |
When to use |
| OverallSummaryReport |
Total emissions for all subscriptions scopes and date range specified in the input. |
High level report data required |
| MonthlySummaryReport |
Emissions for all subscriptions and emissions scopes for each month specified in the date range. |
Monthly breakdown |
| TopItemsSummaryReport |
Emissions of top X items aggregated across subscriptions, emissions, scope, category, and specified date range, broken down by category. |
Data for the top items by category |
| TopItemsMonthlySummaryReport |
Emissions of the top X items aggregated across subscriptions, emissions, scopes, and category for each month specified in the date range. Emissions are broken down by category. The top X items are based on last month's emissions. |
Data for top items by category and month |
| ItemDetailsReport |
Emissions aggregated across selected scopes and subscriptionsIDs for a given date range and broken down by specified category. |
Emissions data by category |
Export emissions API parameters
The following table describes the parameters that you can use to export emissions data using the REST API.
| Parameter |
Type |
Description |
reportType |
String |
Report type name. Supported values: OverallSummaryReport
MonthlySummaryReport
TopItemsSummaryReport TopItemsMonthlySummaryReport ItemDetailsReport |
subscriptionList |
[String] |
The subscriptionId list that you want to query for. The client should have access to these subscriptions. |
resourceGroupUrlList |
[String] |
The resourceGroup url list that you want to get data for. For example: "resourceGroupUrlList": [ "/subscriptions/sub-id-1111/resourcegroups/rg_name" ] The string value in array must follow this format: "/subscriptions/{sub_id}/resourcegroups/{rg_name}" |
carbonScopeList |
[String] |
The carbon scope list. Supported values: Scope1, Scope2 and Scope3. This list can be any combination of these three scopes. |
dateRange |
Struct |
Supports one month from the last 12 months. The start and end month should be equal and it should be the first day of a month. An exception is thrown when when this criteria is not met. For example, dateRange": { "start": "2023-03-01", "end": "2023-03-01} start and end format: yyyy-mm-dd.
Currently, carbon emissions data is refreshed monthly. So, the dateRange start and end properties value must be the first day of each month. |
Note
dateRange supports one month at a time (from the last 12 month). An exception is thrown when start and end dates are different.
Report-specific parameters
The following table shows additional parameters that are required for each report type.
| AdditionalParameter |
Type |
Description |
Reports |
categoryType |
String |
Five category types are supported: Subscription
Location
ServiceType
ResourceGroup
Resource
|
TopItemsSummaryReportTopItemsMonthlySummaryReport
ItemDetailsReport
|
topItemsCount |
Integer |
The top x items to show (>5) |
TopItemsSummaryReportTopItemsMonthlySummaryReport
|
ItemDetailsReport |
category |
String |
The category name. For example, "category": "ResourceGroup" |
pageSize |
Integer |
The page size for the query result. The default value is 1000. The maximum value is 2000. |
ItemDetailsReport |
orderBy |
String |
See the table below to see the supported values, along with the supported Category Types. |
ItemDetailsReport |
sortDirection |
String |
Support values: Desc, Asc |
ItemDetailsReport |
groupCategory |
String |
This can be set as an empty string. Valid values: ResourceGroup and SubscriptionId |
ItemDetailsReport |
Order by columns
The following result columns support the orderBy parameter.
| Order by column name |
Category Type |
Name |
all except Subscription |
TotalCarbonEmission |
all |
TotalCarbonEmissionLastMonth |
all |
ResourceGroup |
only for Resource category |
SubscriptionId |
Subscription, Resource and ResourceGroup Category |
ChangeRatioForLastMonth |
all |
ChangeValueMonthOverMonth |
all |
For more information on the REST API reports, see Carbon Service - List Carbon Emission Reports.
