Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This article helps you understand and use the latest Carbon Service REST API to export Carbon optimization in Azure emissions data. Emissions data is available for the previous month by day 19 of the current month.
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
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. 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.
- Assign the app a role at the scope of the data you want to export: a subscription-level role for subscription requests, or a supported billing account-level role for billing account requests. For more information, see Assign access to Carbon optimization in Azure.
Get an authorization token
Send the following POST request in the command prompt or by using a client.
Use the resource URL https://management.azure.com to get an access token for the resource management API.
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 as follows:
{
"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
For subscription-level requests, use the following POST request and include subscriptionList in the body:
POST /providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
Host: management.azure.com
Content-Type: application/json
Authorization: Bearer \<token value\>
Export emissions data using the REST API at the billing account level
For billing account-level requests, use the following endpoint with a billing account or enrollment identifier. The following example omits the optional subscriptionList. Billing account requests include all subscriptions under the specified billing account.
POST /providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
Host: management.azure.com
Content-Type: application/json
Authorization: Bearer <token value>
Example request and response
POST https://management.azure.com/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
{
"reportType": "MonthlySummaryReport",
"subscriptionList": [
"00000000-0000-0000-0000-000000000000"
],
"carbonScopeList": [
"Scope1",
"Scope3"
],
"dateRange": {
"start": "2024-03-01",
"end": "2024-05-01"
}
}
Sample output
{
"subscriptionAccessDecisionList": [
{
"subscriptionId": "00000000-0000-0000-0000-000000000000",
"decision": "Allowed"
}
],
"value": [
{
"dataType": "MonthlySummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05
}
]
}
The following billing account-level summary example omits the optional subscriptionList:
POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
{
"reportType": "MonthlySummaryReport",
"carbonScopeList": ["Scope1", "Scope3"],
"dateRange": {
"start": "2024-03-01",
"end": "2024-05-01"
}
}
The billing-account response doesn't include subscriptionAccessDecisionList:
{
"value": [
{
"dataType": "MonthlySummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05
}
]
}
Here's a curl example:
curl --location 'https://management.azure.com/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXA...2-KgVBNrsvg' \
--data '{
"reportType": "ItemDetailsReport",
"subscriptionList": [
"00000000-0000-0000-0000-000000000000",
"00000000-0000-0000-0000-000000000001,",
"00000000-0000-0000-0000-000000000002",
"00000000-0000-0000-0000-000000000003",
"00000000-0000-0000-0000-000000000004",
"00000000-0000-0000-0000-000000000005",
"00000000-0000-0000-0000-000000000006",
"00000000-0000-0000-0000-000000000007",
"00000000-0000-0000-0000-000000000008"
],
"carbonScopeList": [
"Scope1",
"Scope3"
],
"dateRange": {
"start": "2024-05-01",
"end": "2024-05-01"
},
"categoryType": "Resource",
"orderBy": "LatestMonthEmissions",
"sortDirection": "Desc",
"pageSize": 100
}
'
Sample curl output:
{
"subscriptionAccessDecisionList": [
{
"subscriptionId": "00000000-0000-0000-0000-000000000000",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000001",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000002",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000003",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000004",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000005",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000006",
"decision": "Denied"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000007",
"decision": "Denied"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000008",
"decision": "Denied",
"denialReason": "Carbon Optimization Reader permisison required"
}
],
"value": [
{
"dataType": "ResourceItemDetailsData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "rgName1",
"resourceGroup": "rgGroup",
"resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rgGroup/providers/microsoft.storage/storageaccounts/rgName1",
"subscriptionId": "00000000-0000-0000-0000-000000000000",
"categoryType": "Resource",
"resourceType": "microsoft.storage/storageaccounts",
"location": "east us"
},
{
"dataType": "ResourceItemDetailsData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "rgName2",
"resourceGroup": "rgGroup",
"resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rgGroup/providers/microsoft.storage/storageaccounts/rgName2",
"subscriptionId": "00000000-0000-0000-0000-000000000000",
"categoryType": "Resource",
"resourceType": "microsoft.storage/storageaccounts",
"location": "east us"
},
{
"dataType": "ResourceItemDetailsData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "rgName3",
"resourceGroup": "rgGroup",
"resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rgGroup/providers/microsoft.storage/storageaccounts/rgName3",
"subscriptionId": "00000000-0000-0000-0000-000000000000",
"categoryType": "Resource",
"resourceType": "microsoft.storage/storageaccounts",
"location": "east us"
},
{
"dataType": "ResourceItemDetailsData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "rgName4",
"resourceGroup": "rgGroup",
"resourceId": "/subscriptions/00000000-0000-0000-0000-000000000002/resourceGroups/rgGroup/providers/microsoft.storage/storageaccounts/rgName4",
"subscriptionId": "00000000-0000-0000-0000-000000000002",
"categoryType": "Resource",
"resourceType": "microsoft.storage/storageaccounts",
"location": "east us"
},
{
"dataType": "ResourceItemDetailsData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "rgName5",
"resourceGroup": "rgGroup",
"resourceId": "/subscriptions/00000000-0000-0000-0000-000000000002/resourceGroups/rgGroup/providers/microsoft.storage/storageaccounts/rgName5",
"subscriptionId": "00000000-0000-0000-0000-000000000002",
"categoryType": "Resource",
"resourceType": "microsoft.storage/storageaccounts",
"location": "east us"
}
],
"skipToken": "dGVzZGZhZGZzZnNkZg=="
}
For a billing account-level item details request, use the same filter without subscriptionList:
curl --location 'https://management.azure.com/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token value>' \
--data '{
"reportType": "ItemDetailsReport",
"carbonScopeList": ["Scope1", "Scope3"],
"dateRange": {"start": "2024-05-01", "end": "2024-05-01"},
"categoryType": "Resource",
"orderBy": "LatestMonthEmissions",
"sortDirection": "Desc",
"pageSize": 100
}'
The response has ResourceItemDetailsData entries and can contain a skipToken for the next page:
{
"value": [
{
"dataType": "ResourceItemDetailsData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "rgName1",
"resourceGroup": "rgGroup",
"resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rgGroup/providers/microsoft.storage/storageaccounts/rgName1",
"subscriptionId": "00000000-0000-0000-0000-000000000000",
"categoryType": "Resource",
"resourceType": "microsoft.storage/storageaccounts",
"location": "east us"
}
],
"skipToken": "dGVzZGZhZGZzZnNkZg=="
}
Report types
Carbon optimization provides various report types to help you analyze your emissions data. Each report type serves a different purpose and is used for your specific needs:
| Report type | Description | When to use |
|---|---|---|
| OverallSummaryReport | Provides total carbon emissions for the specified date range and query parameters, and comparative values for a high-level overview. This report type accepts different values in the start and end fields within DateRange. For example, start: 2024-03-01 and end: 2024-06-01. | High level report data required |
| MonthlySummaryReport | Provides carbon emissions data by month for the specified query parameters. This report type accepts different values in the start and end fields within DateRange. For example, start: 2024-03-01 and end: 2024-06-01. | Details for a specified month |
| TopItemsSummaryReport | Provides the N highest-emitting items for the specified query filters. This report returns data for a single month at a time, so it requires the same values for the start and end fields within DateRange. A maximum of N=10 items are returned at a time. | Data for the top items by category |
| TopItemsMonthlySummaryReport | Provides the N highest-emitting items by month for the specified query filter. Returns emissions data for the top N items by month within the given date range. A maximum of N=10 items are returned at a time. | Data for top items by category and month |
| ItemDetailsReport | A granular list of items based on the specified CategoryType (including: Resource, ResourceGroup, ResourceType, Location, or Subscription) for the query filter. You can query for only one month at a time. The DateRange requires the same values for the start and end fields. | Emissions data by category |
Export emissions API parameters
For each reportType, different query parameters are defined. The following sections provide detailed information about the query parameters for each reportType.
| Name | Required | Type | Description |
|---|---|---|---|
billingAccountId |
Conditional | string | Billing account identifier in the request URI. Required for billing account-level requests; omit for subscription-level requests. |
| Name | Description |
|---|---|
| ItemDetailsQueryFilter | Query parameters for ItemDetailsReport |
| MonthlySummaryReportQueryFilter | Query filter parameters to configure MonthlySummaryReport queries. |
| OverallSummaryReportQueryFilter | Query filter parameters to configure OverallSummaryReport queries. |
| TopItemsMonthlySummaryReportQueryFilter | Query filter parameters to configure TopItemsMonthlySummaryReport queries. |
| TopItemsSummaryReportQueryFilter | Query filter parameters to configure TopItemsSummaryReport queries. |
For more information on the REST API reports, see the Carbon Service REST API reference.
ItemDetailsQueryFilter
Here are the query parameters for ItemDetailsReport.
| Name | Required | Type | Description |
|---|---|---|---|
| carbonScopeList | True | EmissionScopeEnum[] | List of carbon emission scopes. Required. Accepts one or more values from EmissionScopeEnum. For example, Scope1, Scope2, Scope3 in list form. The output includes the total emissions for the specified scopes. |
| categoryType | True | CategoryTypeEnum | Specifies the category type for detailed emissions data, such as Resource, ResourceGroup, ResourceType, Location, or Subscription. See supported types in CategoryTypeEnum. |
| dateRange | True | DateRange | The start and end dates for carbon emissions data. Required. For ItemDetailsReport and TopItemsSummaryReport, only one month of data is supported at a time, so start and end dates should be equal within DateRange. For example, start: 2024-06-01 and end: 2024-06-01. |
| orderBy | True | OrderByColumnEnum | The column name to order the results by. See supported values in OrderByColumnEnum. |
| pageSize | True | integer (int32) minimum: 1 maximum: 5000 |
Number of items to return in one request, maximum value is 5000. |
| reportType | True | string: ItemDetailsReport |
The ReportType requested for carbon emissions data. Required. Specifies how data is aggregated and displayed in the output, as explained in the ReportTypeEnum. |
| sortDirection | True | SortDirectionEnum | Direction for sorting results. See supported values in SortDirectionEnum. |
| subscriptionList | Conditional | string[] | Subscription IDs for subscription-level requests; optional for billing account-level requests. Each ID must be lowercase, with a limit of 100 subscriptions per subscription-level request. Billing account-level requests include all subscriptions in the specified billing account without a subscription-count limit. |
| locationList | string[] | List of locations (Azure Region display name) for carbon emissions data, with each location specified in lowercase. For example, east us. Optional. You can use the command az account list-locations -o table to find Azure Region display names. |
|
| resourceGroupUrlList | string[] | List of resource group URLs for carbon emissions data. Optional. Each URL must follow the format /subscriptions/{subscriptionId}/resourcegroups/{resourceGroup}, and should be in all lowercase. |
|
| resourceTypeList | string[] | List of resource types for carbon emissions data. Optional. Each resource type should be specified in lowercase, following the format microsoft.{service}/{resourceType}. For example, microsoft.storage/storageaccounts. |
|
| skipToken | string | Pagination token for fetching the next page of data. This token is nullable and is returned in the previous response if other data pages are available. |
MonthlySummaryReportQueryFilter
Here are the query filter parameters to configure MonthlySummaryReport queries.
| Name | Required | Type | Description |
|---|---|---|---|
| carbonScopeList | True | EmissionScopeEnum[] | List of carbon emission scopes. Required. Accepts one or more values from EmissionScopeEnum. For example, Scope1, Scope2, Scope3 in list form. The output includes the total emissions for the specified scopes. |
| dateRange | True | DateRange | The start and end dates for carbon emissions data. Required. For ItemDetailsReport and TopItemsSummaryReport, only one month of data is supported at a time, so start and end dates should be equal within DateRange. For example, start: 2024-06-01 and end: 2024-06-01. |
| reportType | True | string: MonthlySummaryReport |
The ReportType requested for carbon emissions data. Required. Specifies how data is aggregated and displayed in the output, as explained in the ReportTypeEnum. |
| subscriptionList | Conditional | string[] | Subscription IDs for subscription-level requests; optional for billing account-level requests. Each ID must be lowercase, with a limit of 100 subscriptions per subscription-level request. Billing account-level requests include all subscriptions in the specified billing account without a subscription-count limit. |
| locationList | string[] | List of locations (Azure Region display name) for carbon emissions data, with each location specified in lowercase. For example, east us. Optional. You can use the command az account list-locations -o table to find Azure Region display names. |
|
| resourceGroupUrlList | string[] | List of resource group URLs for carbon emissions data. Optional. Each URL must follow the format /subscriptions/{subscriptionId}/resourcegroups/{resourceGroup}, and should be in all lowercase. |
|
| resourceTypeList | string[] | List of resource types for carbon emissions data. Optional. Each resource type should be specified in lowercase, following the format microsoft.{service}/{resourceType}. For example, microsoft.storage/storageaccounts. |
OverallSummaryReportQueryFilter
Here are the query filter parameters to configure OverallSummaryReport queries.
| Name | Required | Type | Description |
|---|---|---|---|
| carbonScopeList | True | EmissionScopeEnum[] | List of carbon emission scopes. Required. Accepts one or more values from EmissionScopeEnum. For example, Scope1, Scope2, Scope3 in list form. The output includes the total emissions for the specified scopes. |
| dateRange | True | DateRange | The start and end dates for carbon emissions data. Required. For ItemDetailsReport and TopItemsSummaryReport, only one month of data is supported at a time, so start and end dates should be equal within DateRange. For example, start: 2024-06-01 and end: 2024-06-01. |
| reportType | True | string: OverallSummaryReport |
The ReportType requested for carbon emissions data. Required. Specifies how data is aggregated and displayed in the output, as explained in the ReportTypeEnum. |
| subscriptionList | Conditional | string[] | Subscription IDs for subscription-level requests; optional for billing account-level requests. Each ID must be lowercase, with a limit of 100 subscriptions per subscription-level request. Billing account-level requests include all subscriptions in the specified billing account without a subscription-count limit. |
| locationList | string[] | List of locations (Azure Region display name) for carbon emissions data, with each location specified in lowercase. For example, east us. Optional. You can use the command az account list-locations -o table to find Azure Region display names. |
|
| resourceGroupUrlList | string[] | List of resource group URLs for carbon emissions data. Optional. Each URL must follow the format /subscriptions/{subscriptionId}/resourcegroups/{resourceGroup}, and should be in all lowercase. |
|
| resourceTypeList | string[] | List of resource types for carbon emissions data. Optional. Each resource type should be specified in lowercase, following the format microsoft.{service}/{resourceType}. For example, microsoft.storage/storageaccounts. |
TopItemsMonthlySummaryReportQueryFilter
Here are the query filter parameters to configure TopItemsMonthlySummaryReport queries.
| Name | Required | Type | Description |
|---|---|---|---|
| carbonScopeList | True | EmissionScopeEnum[] | List of carbon emission scopes. Required. Accepts one or more values from EmissionScopeEnum. For example, Scope1, Scope2, Scope3 in list form. The output includes the total emissions for the specified scopes. |
| categoryType | True | CategoryTypeEnum | Specifies the category type to retrieve top-emitting items, aggregated by month. See supported types in CategoryTypeEnum. |
| dateRange | True | DateRange | The start and end dates for carbon emissions data. Required. For ItemDetailsReport and TopItemsSummaryReport, only one month of data is supported at a time, so start and end dates should be equal within DateRange. For example, start: 2024-06-01 and end: 2024-06-01. |
| reportType | True | string: TopItemsMonthlySummaryReport |
The ReportType requested for carbon emissions data. Required. Specifies how data is aggregated and displayed in the output, as explained in the ReportTypeEnum. |
| subscriptionList | Conditional | string[] | Subscription IDs for subscription-level requests; optional for billing account-level requests. Each ID must be lowercase, with a limit of 100 subscriptions per subscription-level request. Billing account-level requests include all subscriptions in the specified billing account without a subscription-count limit. |
| topItems | True | integer (int32) minimum: 1 maximum: 10 |
The number of top items to return, based on emissions. Must be between 1 and 10. |
| locationList | string[] | List of locations (Azure Region display name) for carbon emissions data, with each location specified in lowercase. For example, east us. Optional. You can use the command az account list-locations -o table to find Azure Region display names. |
|
| resourceGroupUrlList | string[] | List of resource group URLs for carbon emissions data. Optional. Each URL must follow the format /subscriptions/{subscriptionId}/resourcegroups/{resourceGroup}, and should be in all lowercase. |
|
| resourceTypeList | string[] | List of resource types for carbon emissions data. Optional. Each resource type should be specified in lowercase, following the format microsoft.{service}/{resourceType}. For example, microsoft.storage/storageaccounts. |
TopItemsSummaryReportQueryFilter
Here are the query filter parameters to configure TopItemsSummaryReport queries.
| Name | Required | Type | Description |
|---|---|---|---|
| carbonScopeList | True | EmissionScopeEnum[] | List of carbon emission scopes. Required. Accepts one or more values from EmissionScopeEnum. For example, Scope1, Scope2, Scope3 in list form. The output includes the total emissions for the specified scopes. |
| categoryType | True | CategoryTypeEnum | Specifies the category type for which to retrieve top-emitting items. See supported values defined in CategoryTypeEnum. |
| dateRange | True | DateRange | The start and end dates for carbon emissions data. Required. For ItemDetailsReport and TopItemsSummaryReport, only one month of data is supported at a time, so start and end dates should be equal within DateRange. For example, start: 2024-06-01 and end: 2024-06-01. |
| reportType | True | string: TopItemsSummaryReport |
The ReportType requested for carbon emissions data. Required. Specifies how data is aggregated and displayed in the output, as explained in the ReportTypeEnum. |
| subscriptionList | Conditional | string[] | Subscription IDs for subscription-level requests; optional for billing account-level requests. Each ID must be lowercase, with a limit of 100 subscriptions per subscription-level request. Billing account-level requests include all subscriptions in the specified billing account without a subscription-count limit. |
| topItems | True | integer (int32) minimum: 1 maximum: 10 |
The number of top items to return, based on emissions. This value must be between 1 and 10. |
| locationList | string[] | List of locations (Azure Region display name) for carbon emissions data, with each location specified in lowercase. For example, east us. Optional. You can use the command az account list-locations -o table to find Azure Region display names. |
|
| resourceGroupUrlList | string[] | List of resource group URLs for carbon emissions data. Optional. Each URL must follow the format /subscriptions/{subscriptionId}/resourcegroups/{resourceGroup}, and should be in all lowercase. |
|
| resourceTypeList | string[] | List of resource types for carbon emissions data. Optional. Each resource type should be specified in lowercase, following the format microsoft.{service}/{resourceType}. For example, microsoft.storage/storageaccounts. |
Sample reports
The following sections show sample requests and responses for each report type.
Subscription-level reports include subscriptionAccessDecisionList, which shows the access decision for each input subscription. Billing account-level reports don't include this field.
OverallSummaryReport
The report shows total emissions for all subscriptions scopes and date range specified in the input. Use the report when you need high-level report data.
Sample request
POST https://management.azure.com/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
{
"reportType": "OverallSummaryReport",
"subscriptionList": [
"00000000-0000-0000-0000-000000000000"
],
"carbonScopeList": [
"Scope1",
"Scope3"
],
"dateRange": {
"start": "2024-03-01",
"end": "2024-05-01"
}
}
Sample response
{
"subscriptionAccessDecisionList": [
{
"subscriptionId": "00000000-0000-0000-0000-000000000000",
"decision": "Allowed"
}
],
"value": [
{
"dataType": "OverallSummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05
}
]
}
Billing account-level sample
POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
{
"reportType": "OverallSummaryReport",
"carbonScopeList": ["Scope1", "Scope3"],
"dateRange": {"start": "2024-03-01", "end": "2024-05-01"}
}
{
"value": [
{
"dataType": "OverallSummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05
}
]
}
MonthlySummaryReport
The report shows emissions for all subscriptions and emissions scopes for the month specified in the date range. Use the report when you need details for a specified month.
Sample request
POST https://management.azure.com/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
{
"reportType": "MonthlySummaryReport",
"subscriptionList": [
"00000000-0000-0000-0000-000000000000"
],
"carbonScopeList": [
"Scope1",
"Scope3"
],
"dateRange": {
"start": "2024-03-01",
"end": "2024-05-01"
}
}
Sample response
{
"subscriptionAccessDecisionList": [
{
"subscriptionId": "00000000-0000-0000-0000-000000000000",
"decision": "Allowed"
}
],
"value": [
{
"dataType": "MonthlySummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"date": "2024-05-01",
"carbonIntensity": 22
},
{
"dataType": "MonthlySummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"date": "2024-04-01",
"carbonIntensity": 22
},
{
"dataType": "MonthlySummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"date": "2024-03-01",
"carbonIntensity": 22
}
]
}
TopItemsSummaryReport
The report shows emissions of the top X items aggregated across subscriptions, emissions, scope, category, and specified date range, broken down by category. Use the report when you need data for the top items by category.
Sample request
POST https://management.azure.com/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
{
"reportType": "TopItemsSummaryReport",
"subscriptionList": [
"00000000-0000-0000-0000-000000000000",
"00000000-0000-0000-0000-000000000001,",
"00000000-0000-0000-0000-000000000002",
"00000000-0000-0000-0000-000000000003",
"00000000-0000-0000-0000-000000000004",
"00000000-0000-0000-0000-000000000005",
"00000000-0000-0000-0000-000000000006",
"00000000-0000-0000-0000-000000000007",
"00000000-0000-0000-0000-000000000008"
],
"carbonScopeList": [
"Scope1",
"Scope3"
],
"dateRange": {
"start": "2024-05-01",
"end": "2024-05-01"
},
"categoryType": "Location",
"topItems": 5
}
Sample response
{
"subscriptionAccessDecisionList": [
{
"subscriptionId": "00000000-0000-0000-0000-000000000000",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000001",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000002",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000003",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000004",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000005",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000006",
"decision": "Denied"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000007",
"decision": "Denied"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000008",
"decision": "Denied",
"denialReason": "Carbon Optimization Reader permission required"
}
],
"value": [
{
"dataType": "TopItemsSummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "east us",
"categoryType": "Location"
},
{
"dataType": "TopItemsSummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "west us",
"categoryType": "Location"
},
{
"dataType": "TopItemsSummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "west us 2",
"categoryType": "Location"
},
{
"dataType": "TopItemsSummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "west us 3",
"categoryType": "Location"
},
{
"dataType": "TopItemsSummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "east us 2",
"categoryType": "Location"
}
]
}
Billing account-level sample
POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
{
"reportType": "TopItemsSummaryReport",
"carbonScopeList": ["Scope1", "Scope3"],
"dateRange": {"start": "2024-05-01", "end": "2024-05-01"},
"categoryType": "Location",
"topItems": 5
}
{
"value": [
{"dataType": "TopItemsSummaryData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "east us", "categoryType": "Location"},
{"dataType": "TopItemsSummaryData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "west us", "categoryType": "Location"},
{"dataType": "TopItemsSummaryData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "west us 2", "categoryType": "Location"},
{"dataType": "TopItemsSummaryData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "west us 3", "categoryType": "Location"},
{"dataType": "TopItemsSummaryData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "east us 2", "categoryType": "Location"}
]
}
TopItemsMonthlySummaryReport
The report shows emissions of the top X items aggregated across subscriptions, emissions, scopes, and category for each month specified in the date range. Emissions get broken down by category. The top X items are based on last month's emissions. Use the report when you need data for top items by category and month.
Sample request
POST https://management.azure.com/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
{
"reportType": "TopItemsMonthlySummaryReport",
"subscriptionList": [
"00000000-0000-0000-0000-000000000000",
"00000000-0000-0000-0000-000000000001,",
"00000000-0000-0000-0000-000000000002",
"00000000-0000-0000-0000-000000000003",
"00000000-0000-0000-0000-000000000004",
"00000000-0000-0000-0000-000000000005",
"00000000-0000-0000-0000-000000000006",
"00000000-0000-0000-0000-000000000007",
"00000000-0000-0000-0000-000000000008"
],
"carbonScopeList": [
"Scope1",
"Scope3"
],
"dateRange": {
"start": "2024-03-01",
"end": "2024-05-01"
},
"categoryType": "Location",
"topItems": 2
}
Sample response
{
"subscriptionAccessDecisionList": [
{
"subscriptionId": "00000000-0000-0000-0000-000000000000",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000001",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000002",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000003",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000004",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000005",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000006",
"decision": "Denied"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000007",
"decision": "Denied"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000008",
"decision": "Denied",
"denialReason": "Carbon Optimization Reader permission required"
}
],
"value": [
{
"dataType": "TopItemsMonthlySummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "east us",
"categoryType": "Location",
"date": "2024-05-01"
},
{
"dataType": "TopItemsMonthlySummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "east us",
"categoryType": "Location",
"date": "2024-04-01"
},
{
"dataType": "TopItemsMonthlySummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "east us",
"categoryType": "Location",
"date": "2024-03-01"
},
{
"dataType": "TopItemsMonthlySummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "west us",
"categoryType": "Location",
"date": "2024-05-01"
},
{
"dataType": "TopItemsMonthlySummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "west us",
"categoryType": "Location",
"date": "2024-04-01"
},
{
"dataType": "TopItemsMonthlySummaryData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "west us",
"categoryType": "Location",
"date": "2024-03-01"
}
]
}
Billing account-level sample
POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
{
"reportType": "TopItemsMonthlySummaryReport",
"carbonScopeList": ["Scope1", "Scope3"],
"dateRange": {"start": "2024-03-01", "end": "2024-05-01"},
"categoryType": "Location",
"topItems": 2
}
{
"value": [
{"dataType": "TopItemsMonthlySummaryData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "east us", "categoryType": "Location", "date": "2024-05-01"},
{"dataType": "TopItemsMonthlySummaryData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "east us", "categoryType": "Location", "date": "2024-04-01"},
{"dataType": "TopItemsMonthlySummaryData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "east us", "categoryType": "Location", "date": "2024-03-01"},
{"dataType": "TopItemsMonthlySummaryData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "west us", "categoryType": "Location", "date": "2024-05-01"},
{"dataType": "TopItemsMonthlySummaryData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "west us", "categoryType": "Location", "date": "2024-04-01"},
{"dataType": "TopItemsMonthlySummaryData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "west us", "categoryType": "Location", "date": "2024-03-01"}
]
}
ItemDetailsReport
The report shows emissions aggregated across selected scopes and subscription IDs for a given date range and broken down by specified category. Use the report when you need emissions data by category and to get resource group and resource-level data.
Sample request
POST https://management.azure.com/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
{
"reportType": "ItemDetailsReport",
"subscriptionList": [
"00000000-0000-0000-0000-000000000000",
"00000000-0000-0000-0000-000000000001,",
"00000000-0000-0000-0000-000000000002",
"00000000-0000-0000-0000-000000000003",
"00000000-0000-0000-0000-000000000004",
"00000000-0000-0000-0000-000000000005",
"00000000-0000-0000-0000-000000000006",
"00000000-0000-0000-0000-000000000007",
"00000000-0000-0000-0000-000000000008"
],
"carbonScopeList": [
"Scope1",
"Scope3"
],
"dateRange": {
"start": "2024-05-01",
"end": "2024-05-01"
},
"categoryType": "Location",
"orderBy": "LatestMonthEmissions",
"sortDirection": "Desc",
"pageSize": 100
}
Sample response
{
"subscriptionAccessDecisionList": [
{
"subscriptionId": "00000000-0000-0000-0000-000000000000",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000001",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000002",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000003",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000004",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000005",
"decision": "Allowed"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000006",
"decision": "Denied"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000007",
"decision": "Denied"
},
{
"subscriptionId": "00000000-0000-0000-0000-000000000008",
"decision": "Denied",
"denialReason": "Carbon Optimization Reader permission required"
}
],
"value": [
{
"dataType": "ItemDetailsData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "east us",
"categoryType": "Location"
},
{
"dataType": "ItemDetailsData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "west us",
"categoryType": "Location"
},
{
"dataType": "ItemDetailsData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "west us 2",
"categoryType": "Location"
},
{
"dataType": "ItemDetailsData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "west us 3",
"categoryType": "Location"
},
{
"dataType": "ItemDetailsData",
"latestMonthEmissions": 0.1,
"previousMonthEmissions": 0.05,
"monthOverMonthEmissionsChangeRatio": 1,
"monthlyEmissionsChangeValue": 0.05,
"itemName": "east us 2",
"categoryType": "Location"
}
]
}
Billing account-level sample
POST https://management.azure.com/providers/Microsoft.Billing/billingAccounts/{billingAccountId}/providers/Microsoft.Carbon/carbonEmissionReports?api-version=2026-05-01-preview
{
"reportType": "ItemDetailsReport",
"carbonScopeList": ["Scope1", "Scope3"],
"dateRange": {"start": "2024-05-01", "end": "2024-05-01"},
"categoryType": "Location",
"orderBy": "LatestMonthEmissions",
"sortDirection": "Desc",
"pageSize": 100
}
{
"value": [
{"dataType": "ItemDetailsData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "east us", "categoryType": "Location"},
{"dataType": "ItemDetailsData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "west us", "categoryType": "Location"},
{"dataType": "ItemDetailsData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "west us 2", "categoryType": "Location"},
{"dataType": "ItemDetailsData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "west us 3", "categoryType": "Location"},
{"dataType": "ItemDetailsData", "latestMonthEmissions": 0.1, "previousMonthEmissions": 0.05, "monthOverMonthEmissionsChangeRatio": 1, "monthlyEmissionsChangeValue": 0.05, "itemName": "east us 2", "categoryType": "Location"}
]
}