Share via

Use the API to export Azure carbon optimization emissions data

  • Article

This article helps you understand and use the latest Carbon Service REST API to export Azure carbon optimization 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.

  1. Create a Microsoft Entra application and service principal that can access resources.
  2. Save the tenant ID, new client ID, and client secret value for your app for use in token requests.
  3. The app must be assigned the Carbon Optimization Reader role for the resources that you want to export emissions data for. If you want to use the app to export emissions data for many resources, you can assign the role at the subscription level. For more information, see Assign Azure roles by using the Azure portal and Assign access to Azure carbon optimization.

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

Use the following POST request to export emissions data.

POST /providers/Microsoft.Carbon/carbonEmissionReports?api-version=2025-04-01
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=2025-04-01

{
  "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": "OverallSummaryData",
      "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=2025-04-01' \
--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=="
}

Report types

Azure 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 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 Carbon Service - List Carbon Emission Reports.

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 True string[] List of subscription IDs for which carbon emissions data is requested. Required. Each subscription ID should be in lowercase format. The maximum length of the list is 100.
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 True string[] List of subscription IDs for which carbon emissions data is requested. Required. Each subscription ID should be in lowercase format. The maximum length of the list is 100.
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 True string[] List of subscription IDs for which carbon emissions data is requested. Required. Each subscription ID should be in lowercase format. The maximum length of the list is 100.
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 True string[] List of subscription IDs for which carbon emissions data is requested. Required. Each subscription ID should be in lowercase format. The maximum length of the list is 100.
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 True string[] List of subscription IDs for which carbon emissions data is requested. Required. Each subscription ID should be in lowercase format. The maximum length of the list is 100.
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.

All reports include the subscriptionAccessDecisionList response. The field shows the access decision for each input subscription.

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=2025-04-01

{
  "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": "OverallSummaryData",
      "latestMonthEmissions": 0.1,
      "previousMonthEmissions": 0.05,
      "monthOverMonthEmissionsChangeRatio": 1,
      "monthlyEmissionsChangeValue": 0.05
    }
  ]
}

Related content