IBM Cloud API Docs

Introduction

Last updated: 2023-10-03

The carbon calculator provides a wide range of features to track carbon emissions for an account, which enables you to track and reduce your carbon footprint over time. You can view total emissions by service, resource group, location, and resource group.

The code examples on this tab use the client library that is provided for Java.

Maven

<dependency>
    <groupId>com.ibm.cloud</groupId>
	<artifactId>carbon-calculator</artifactId>
	<version>{version}</version>
</dependency>

Gradle

'com.ibm.cloud:carbon-calculator:{version}'

View on GitHub

https://github.com/IBM/platform-services-java-sdk

Endpoint URLs

The carbon calculator API uses the following global endpoint URL. When you call the API, add the path for each method to form the complete API endpoint for your requests.

https://api.carbon-calculator.cloud.ibm.com

Example API request

curl -X {request_method} "https://api.carbon-calculator.test.cloud.ibm.com/{method_endpoint}"

Replace {request_method} and {method_endpoint} in this example with the values for your particular API call.

Authentication

Authentication to the carbon calculator REST API is enforced by using an IAM access token. The token is used to determine the identity and access roles for management services. You need the IAM token that has account information. If you generate an IAM token through an API, don't forget to add the account information. For information about how to obtain an IAM token for an authenticated user or service ID, see the IAM Identity Service API documentation.

Use of the IAM Policy Management REST API is done by adding a valid IAM Token to the HTTP Authorization request header. Example: -H 'Authorization: Bearer $TOKEN'

Obtaining an IAM token for an authenticated user or service ID is described in the IAM Identity Services API documentation.

To use the API, add a valid IAM token to the HTTP Authorization request header, for example, -H 'Authorization: Bearer <TOKEN>'.

To retrieve your access token:

curl -X POST   "https://iam.test.cloud.ibm.com/identity/token"   --header 'Content-Type: application/x-www-form-urlencoded'   --header 'Accept: application/json'   --data-urlencode 'grant_type=$grantType'   --data-urlencode 'apikey=$apiKey'

Replace <API_KEY> with your IAM API key.

Auditing

List of Activity Tracker Events:

Action	Description
carbon-calculator.carbon-emissions.list	Request to get the carbon emissions for a given account.
carbon-calculator.services.list	Request a list of services where carbon emissions can be returned.
carbon-calculator.locations.list	Request a list of services where carbon emissions can be returned.

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

Table 1. HTTP Status Codes
HTTP Error Code	Description	Recovery
`200`	Success	The request was successful.
`400`	Bad Request	The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
`401`	Unauthorized	You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
`403`	Forbidden	The supplied authentication is not authorized to access.
`404`	Not Found	The requested resource could not be found.
`500`	Internal Server Error	Carbon calculator is currently unavailable. Your request could not be processed. Wait a few minutes and try again.

Table 2. Request Headers
Header	Description
`Authorization`	JWT bearer token generated using IAM PEP endpoint.
`Accept`	application/json

Methods

Get a list of services that offer data for the carbon calculator.

GET /v1/services

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following actions, depending on any listed conditions. You can check your access by going to Users > User > Access.

billing.carbon-calculator.read
Required when trying to fetch locations for standard cloud account.
enterprise.enterprise.retrieve
Required when trying to fetch locations for enterprise cloud account.

Auditing

Calling this method generates the following auditing event.

carbon-calculator.services.list

Request

Query Parameters

limit
integer
Page limit to be set when fetching list of services.

Possible values: 1 ≤ value ≤ 100
Default: 10
Example: 10
offset
integer
Page offset to be set when fetching list of services.

Possible values: 0 ≤ value ≤ 2147483647
Default: 0
Example: 10

Example request

curl --location 'https://api.carbon-calculator.cloud.ibm.com/v1/services?limit=10&offset=0'
--header 'Accept: application/json'

Response

Response Body

ServiceCollection

Collection of Services returned in the List Services Endpoint.

Status Code

200
OK
400
Bad Request
401
Unauthorized
403
Forbidden

Example responses

Status 200

healthy response

{
  "services": [
    {
      "id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "name": "Bare Metal Server for VPC"
    },
    {
      "id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "name": "Bare Metal Server for Classic"
    }
  ],
  "offset": 10,
  "limit": 10,
  "total_count": 104,
  "first": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/services?offset=0&limit=10"
  },
  "last": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/services?offset=100&limit=10"
  },
  "previous": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/services?offset=0&limit=10"
  },
  "next": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/services?offset=20&limit=10"
  }
}

Status 401

unauthenticated request

{
  "timestamp": "2023-04-26T11:50:03.700Z",
  "status": "401",
  "error": "Unauthorized",
  "message": "Token not specified.",
  "path": "/v1/services",
  "trace": ""
}

Status 403

unauthorized request

{
  "timestamp": "2023-04-26T11:50:03.700Z",
  "status": "401",
  "error": "Unauthorized",
  "message": "Token not specified.",
  "path": "/v1/services",
  "trace": ""
}

Get list of locations that offer data for the carbon calculator.

GET /v1/locations

Authorization

billing.carbon-calculator.read
Required when trying to fetch locations for standard cloud account.
enterprise.enterprise.retrieve
Required when trying to fetch locations for enterprise cloud account.

Auditing

Calling this method generates the following auditing event.

carbon-calculator.locations.list

Request

Query Parameters

limit
integer
Page limit to be set when fetching list of locations.

Possible values: 1 ≤ value ≤ 100
Default: 10
Example: 10
offset
integer
Page offset to be set when fetching list of locations.

Possible values: 0 ≤ value ≤ 2147483647
Default: 0

Example request

curl --location 'https://api.carbon-calculator.cloud.ibm.com/v1/locations?limit=10&offset=0'
--header 'Accept: application/json'

Response

Response Body

LocationCollection

Location list result container

Status Code

200
OK
400
Bad Request
401
Unauthorized
403
Forbidden

Example responses

Status 200

healthy response

{
  "locations": [
    {
      "name": "Amsterdam"
    },
    {
      "name": "Dallas"
    }
  ],
  "offset": 10,
  "limit": 10,
  "total_count": 104,
  "first": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/locations?offset=0&limit=10"
  },
  "last": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/locations?offset=100&limit=10"
  },
  "previous": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/locations?offset=0&limit=10"
  },
  "next": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/locations?offset=20&limit=10"
  }
}

Status 401

unauthenticated request

{
  "timestamp": "2023-04-26T11:50:03.700Z",
  "status": "401",
  "error": "Unauthorized",
  "message": "Token not specified.",
  "path": "/v1/locations",
  "trace": ""
}

Status 403

unauthorized request

{
  "timestamp": "2023-04-26T11:50:03.700Z",
  "status": "401",
  "error": "Unauthorized",
  "message": "Token not specified.",
  "path": "/v1/locations",
  "trace": ""
}

Lists aggregated carbon emissions.

For a standard account, it is the aggregated carbon emissions associated with the account.
For an enterprise account, it is the aggregated carbon emissions associated with the enterprise, an account group within the enterprise or one of the accounts associated with the enterprise.

GET /v1/carbon_emissions

Authorization

billing.carbon-calculator.read
Required when trying to fetch emissions for standard cloud account.
enterprise.enterprise.retrieve-usage-report
Required when trying to fetch emissions for an enterprise.
enterprise.account-group.retrieve-usage-report
Required when trying to fetch emissions for enterprise account group.
enterprise.account.retrieve-usage-report
Required when trying to fetch emissions for an enterprise account.

Auditing

Calling this method generates the following auditing event.

carbon-calculator.carbon-emissions.list

Request

Query Parameters

month
string[]
Filters the collection to carbon emissions with month property matching provided conditions. This field supports following conditional operations.
- Greater than or equal, by prefixing a value with gte:. Default value would be first month of current year.
- Less than or equal, by prefixing a value with lte:. Default value would be previous month of current year.
Possible values: 0 ≤ number of items ≤ 2, length = 11, Value must match regular expression (gte|lte):(19|20[0-9]{2})-(0[123456789]|1[012])
Examples:
gte_and_lte
lte_only
gte_only
locations
string[]
Filters the collection to carbon emissions with location matching one of the locations.

Possible values: 0 ≤ number of items ≤ 100, 3 ≤ length ≤ 255, Value must match regular expression [A-Za-z ]+
Examples:
Single location
Multiple locations
services
string[]
Filters the collection to carbon emissions with service matching one of the services

Possible values: 0 ≤ number of items ≤ 100, 3 ≤ length ≤ 255, Value must match regular expression [A-Za-z ]+
Examples:
Single service
Multiple services
group_by
string
Groups the carbon emission collection with the specified column/field while performing the sum aggregation operation. | group by | Description | |-----------------|-------------| |month|Request carbon emission resource grouped by the emission month.| |service|Request carbon emission resource grouped by service.| |location|Request carbon emission resource grouped by service.| |resource_group|Request carbon emission resource grouped by resource_group_id.This works only with standard account.Throws error when used with enterprise_id or enterprise_group_id filters| |enterprise_group|Request carbon emission resource grouped by enterprise_group_id.This works only with enteprise account. Throws error when used for standard account filters.| |enterprise_account|Request carbon emission resource grouped by enterprise_account_id.This works only with enteprise account.Throws error when used for standard account filters.|

Allowable values: [month,resource_group,service,location,enterprise_group,enterprise_account]
Possible values: 5 ≤ length ≤ 20, Value must match regular expression [a-z_]+
Default: month
Examples:
Month
Resource Group
Service
Enterprise Account
Enterprise Group
Location
enterprise_account_id
string
Restricts carbon emissions to the specified enterprise account

Possible values: length = 32, Value must match regular expression [a-z0-9]+
Example: x2x261x8x5x84xxxx49x4891xx077xx9
enterprise_group_id
string
Restricts carbon emissions to the specified enterprise group.

Possible values: length = 32, Value must match regular expression [a-z0-9]+
Example: x2x261x8x5x84xxxx49x4891xx077xx9
enterprise_id
string
Restricts carbon emissions to the specified enterprise.

Possible values: length = 32, Value must match regular expression [a-z0-9]+
Example: x2x261x8x5x84xxxx49x4891xx077xx9
limit
integer
Page limit to be set when fetching list of carbon emissions.

Possible values: 1 ≤ value ≤ 100
Default: 100
Example: 10
offset
integer
Page offset to be set when fetching list of carbon emissions.

Possible values: 0 ≤ value ≤ 2147483647
Default: 0
Example: 10

Example request

curl --location 'https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01&month=lte:2023-03&locations=Dallas%2C%20Frankfurt%2C%20Washington%20DC&services=Cloud%20Object%20Storage%2C%20Kubernetes%20Service%2C%20Virtual%20Server%20for%20VPC&group_by=month&enterprise_id=x2x261x8x5x84xxxx49x4891xx077xx9' --header 'Accept: application/json' --header 'Authorization: Bearer {{bearerToken}}'

Response

Response Body

CarbonEmissionCollection

Carbon emission collection provides a list of carbon emission records and overall total carbon emission aggregation data for each list carbon emissions request.

Status Code

200
The carbon calculatons were retrieved successfully.
400
Bad Request
401
Unauthenticated request - an invalid access token was provided.
403
An authenticated access token without proper access to carbon calculator was provided.

Example responses

Status 200: Group by month

Carbon emission aggregated and grouped by month.

{
  "carbon_emissions": [
    {
      "account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "month": {
        "value": "2023-01",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "month",
        "value": "2023-01"
      }
    },
    {
      "account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "carbon_emission": 680,
      "energy_consumption": 5000,
      "month": {
        "value": "2023-02",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "month",
        "value": "2023-02"
      }
    }
  ],
  "total_emission": 2680,
  "offset": 10,
  "limit": 10,
  "total_count": 104,
  "first": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,lte:2023-03&group_by=month&offset=0&limit=10"
  },
  "last": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,lte:2023-03&group_by=month&offset=100&limit=10"
  },
  "previous": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,lte:2023-03&group_by=month&offset=0&limit=10"
  },
  "next": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,month=lte:2023-03&group_by=month&offset=20&limit=10"
  }
}

Status 200: Group by service

Carbon emission aggregated and grouped by service.

{
  "carbon_emissions": [
    {
      "account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "service": "Cloud Object Storage",
      "group_by": {
        "type": "service",
        "value": "Cloud Object Storage"
      },
      "month": {
        "min": "2023-01",
        "max": "2023-02"
      }
    },
    {
      "account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "carbon_emission": 680,
      "energy_consumption": 5000,
      "group_by": {
        "type": "service",
        "value": "Kubernetes service"
      },
      "month": {
        "min": "2023-01",
        "max": "2023-02"
      }
    }
  ],
  "total_emission": 2680,
  "offset": 10,
  "limit": 10,
  "total_count": 104,
  "first": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,lte:2023-03&group_by=service&offset=0&limit=10"
  },
  "last": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,lte:2023-03&group_by=service&offset=100&limit=10"
  },
  "previous": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,lte:2023-03&group_by=service&offset=0&limit=10"
  },
  "next": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,month=lte:2023-03&group_by=service&offset=20&limit=10"
  }
}

Status 200: Group by resource group

Carbon emission aggregated and grouped by resourcegroup.

{
  "carbon_emissions": [
    {
      "account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "resource_group_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "group_by": {
        "type": "resource_group",
        "value": "x2x261x8x5x84xxxx49x4891xx077xx9"
      },
      "month": {
        "min": "2023-01",
        "max": "2023-02"
      }
    },
    {
      "account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "carbon_emission": 680,
      "energy_consumption": 5000,
      "group_by": {
        "type": "resource_group",
        "value": "x2x261x8x5x84xxxx49x4891xx077xx9"
      },
      "month": {
        "min": "2023-01",
        "max": "2023-02"
      }
    }
  ],
  "total_emission": 2680,
  "offset": 10,
  "limit": 10,
  "total_count": 104,
  "first": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,lte:2023-03&group_by=resource_group&offset=0&limit=10"
  },
  "last": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,lte:2023-03&group_by=resource_group&offset=100&limit=10"
  },
  "previous": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,lte:2023-03&group_by=resource_group&offset=0&limit=10"
  },
  "next": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,month=lte:2023-03&group_by=resource_group&offset=20&limit=10"
  }
}

Status 200: Group by location

Carbon emission is aggregated and grouped by location.

{
  "carbon_emissions": [
    {
      "account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "location": "Washington DC",
      "power_utilization_efficiency": 0.55143,
      "carbon_intensity": 1.55143,
      "month": {
        "value": "2023-01",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "location",
        "value": "Washington DC"
      }
    },
    {
      "account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "location": "Dallas",
      "power_utilization_efficiency": 1.2,
      "carbon_intensity": 0.55143,
      "month": {
        "value": "2023-01",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "location",
        "value": "Dallas"
      }
    }
  ],
  "total_emission": 2680,
  "offset": 10,
  "limit": 10,
  "total_count": 104,
  "first": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,lte:2023-03&group_by=month&offset=0&limit=10"
  },
  "last": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,lte:2023-03&group_by=month&offset=100&limit=10"
  },
  "previous": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,lte:2023-03&group_by=month&offset=0&limit=10"
  },
  "next": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?month=gte:2023-01,month=lte:2023-03&group_by=month&offset=20&limit=10"
  }
}

Status 200: List by enterprise account, group by month

Carbon emission filtered by enterprise account, aggregated by month.

{
  "carbon_emissions": [
    {
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "enterprise_account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "month": {
        "value": "2023-01",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "month",
        "value": "2023-01"
      }
    },
    {
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "enterprise_account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "month": {
        "value": "2023-02",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "month",
        "value": "2023-02"
      }
    }
  ],
  "total_emission": 2680,
  "offset": 10,
  "limit": 10,
  "total_count": 104,
  "first": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_account_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=month&offset=0&limit=10"
  },
  "last": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_account_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=month&offset=100&limit=10"
  },
  "previous": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_account_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=month&offset=0&limit=10"
  },
  "next": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_account_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,month=lte:2023-03&group_by=month&offset=20&limit=10"
  }
}

Status 200: List by enterprise group and group by month

Carbon emission filtered by enterprise group, aggregated by month

{
  "carbon_emissions": [
    {
      "account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "enterprise_group_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "month": {
        "value": "2023-01",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "month",
        "value": "2023-01"
      }
    },
    {
      "account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "enterprise_group_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "month": {
        "value": "2023-02",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "month",
        "value": "2023-02"
      }
    }
  ],
  "total_emission": 2680,
  "offset": 10,
  "limit": 10,
  "total_count": 104,
  "first": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_group_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=month&offset=0&limit=10"
  },
  "last": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_group_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=month&offset=100&limit=10"
  },
  "previous": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_group_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=month&offset=0&limit=10"
  },
  "next": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_group_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,month=lte:2023-03&group_by=month&offset=20&limit=10"
  }
}

Status 200: List by enterprise, group by month

Carbon emission filtered by enterprise, aggregated by month

{
  "carbon_emissions": [
    {
      "account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "enterprise_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "month": {
        "value": "2023-01",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "month",
        "value": "2023-01"
      }
    },
    {
      "account_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "enterprise_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "month": {
        "value": "2023-02",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "month",
        "value": "2023-02"
      }
    }
  ],
  "total_emission": 2680,
  "offset": 10,
  "limit": 10,
  "total_count": 104,
  "first": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=month&offset=0&limit=10"
  },
  "last": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=month&offset=100&limit=10"
  },
  "previous": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=month&offset=0&limit=10"
  },
  "next": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_account_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,month=lte:2023-03&group_by=month&offset=20&limit=10"
  }
}

Status 200: List by enterprise, group by enterprise account group

Carbon emission filtered by enterprise, aggregated by enterprise account group

{
  "carbon_emissions": [
    {
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "enterprise_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "month": {
        "value": "2023-01",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "enterprise_group",
        "value": "x2x261x8x5x84xxxx49x4891xx077xx9"
      }
    },
    {
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "enterprise_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "month": {
        "value": "2023-02",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "enterprise_group",
        "value": "x2x261x8x5x84xxxx49x4891xx077xx9"
      }
    }
  ],
  "total_emission": 2680,
  "offset": 10,
  "limit": 10,
  "total_count": 104,
  "first": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_group_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=enterprise_group&offset=0&limit=10"
  },
  "last": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_group_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=enterprise_group&offset=100&limit=10"
  },
  "previous": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_group_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=enterprise_group&offset=0&limit=10"
  },
  "next": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_group_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,month=lte:2023-03&group_by=enterprise_group&offset=20&limit=10"
  }
}

Status 200: List by enterprise, group by enterprise account

Carbon emission filtered by enterprise, aggregated by enterprise account

{
  "carbon_emissions": [
    {
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "enterprise_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "month": {
        "value": "2023-01",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "enterprise_account",
        "value": "x2x261x8x5x84xxxx49x4891xx077xx9"
      }
    },
    {
      "carbon_emission": 2000,
      "energy_consumption": 5000,
      "enterprise_id": "x2x261x8x5x84xxxx49x4891xx077xx9",
      "month": {
        "value": "2023-02",
        "min": "2023-01",
        "max": "2023-02"
      },
      "group_by": {
        "type": "enterprise_account",
        "value": "x2x261x8x5x84xxxx49x4891xx077xx9"
      }
    }
  ],
  "total_emission": 2680,
  "offset": 10,
  "limit": 10,
  "total_count": 104,
  "first": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_group_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=enterprise_account&offset=0&limit=10"
  },
  "last": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_group_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=enterprise_account&offset=100&limit=10"
  },
  "previous": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_group_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,lte:2023-03&group_by=enterprise_account&offset=0&limit=10"
  },
  "next": {
    "href": "https://api.carbon-calculator.cloud.ibm.com/v1/carbon_emissions?&enterprise_group_id=x2x261x8x5x84xxxx49x4891xx077xx9&month=gte:2023-01,month=lte:2023-03&group_by=enterprise_account&offset=20&limit=10"
  }
}

Status 401

Unauthenticated request - an invalid access token was provided.

{
  "timestamp": "2023-04-26T11:50:03.700Z",
  "status": "401",
  "error": "Unauthorized",
  "message": "Token not specified.",
  "path": "/v1/carbon_emissions",
  "trace": ""
}

Status 403

An authenticated access token without proper access to carbon calculator was provided.

{
  "timestamp": "2023-04-26T11:50:03.700Z",
  "status": "403",
  "error": "Forbidden",
  "message": "An authenticated access token without proper access to carbon calculator was provided.",
  "path": "/v1/carbon_emissions",
  "trace": ""
}

Introduction

Endpoint URLs

Authentication

Auditing

List of Activity Tracker Events:

Error handling

Methods

List services

Authorization

Auditing

Request

Query Parameters

limit

offset

Response

Response Body

services

offset

limit

first

last

total_count

next

previous

Status Code

200

400

401

403

List locations

Authorization

Auditing

Request

Query Parameters

limit

offset

Response

Response Body

locations

offset

limit

first

last

total_count

next

previous

Status Code

200

400

401

403

List carbon emissions for a given account

Authorization

Auditing

Request

Query Parameters

month

locations

services

group_by

enterprise_account_id

enterprise_group_id

enterprise_id

limit

offset

Response

Response Body

offset

limit

first

last

carbon_emissions

total_emission

total_count

next

previous

Status Code

200

400

401