The details and examples in this guide will help you get started using the HPE Sustainability Insight Center API for HPE GreenLake cloud.
When forming an HPE Sustainability Insight Center REST API call, choose the hostname that is closest to your region:
- https://us-west.api.greenlake.hpe.com
- https://ap-northeast.api.greenlake.hpe.com
- https://eu-central.api.greenlake.hpe.com
The URIs for the HPE Sustainability Insight Center API endpoints are as follows:
GET /sustainability-insight-ctr/v1beta1/usage-by-entityGET /sustainability-insight-ctr/v1beta1/usage-totalsGET /sustainability-insight-ctr/v1beta1/usage-seriesGET /sustainability-insight-ctr/v1beta1/cloud-usage-by-entityGET /sustainability-insight-ctr/v1beta1/cloud-usage-totalsGET /sustainability-insight-ctr/v1beta1/cloud-usage-seriesGET /sustainability-insight-ctr/v1beta1/coefficientsPOST /sustainability-insight-ctr/v1beta1/coefficientsGET /sustainability-insight-ctr/v1beta1/coefficients/{id}GET /sustainability-insight-ctr/v1beta1/ingestsPOST /sustainability-insight-ctr/v1beta1/ingestsGET /sustainability-insight-ctr/v1beta1/ingests/{id}GET /sustainability-insight-ctr/v1beta1/datasourcesGET /sustainability-insight-ctr/v1beta1/datasources/{id}
Any user with access to the HPE Sustainability Insight Center application has access to both the UI and the API.
You must configure API credentials and generate an access token to make API calls. HPE GreenLake APIs use OAuth-based access tokens used as an authorization bearer token.
To access this HPE GreenLake Sustainability Insight Center API, proceed as follows:
- Create a personal API client.
- Select the HPE GreenLake Cloud Platform service.
- Generate an access token.
- Use the access token as an authorization bearer token to make secure REST API calls.
Run the cURL command below to get the token from the response["access_token"]:
curl -X POST https://sso.common.cloud.hpe.com/as/token.oauth2 -H
"Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id=$YOUR_CLIENT_ID&client_secret=$YOUR_CLIENT_SECRET"This access token is used as the bearer token for the authentication of the HPE Sustainability Insight Center API. The token is valid for two hours.
Run the below API call with the bearer token from the previous step to get energy usage data related to your workspace. The start-time and end-time query parameters are required. The start-time and end-time query parameters must be in ISO 8601 format, for example 2019-10-12T07:20:50.529Z.
GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/usage-by-entity?start-time={{START_TIME}}&end-time={{END_TIME}}&offset=0'Sample API response:
{
"items": [
{
"id": "COMPUTE1234567",
"type": "sustainability-insight-ctr/entities",
"entityId": "COMPUTE1234567",
"entityMake": "HPE",
"entityModel": "PROLIANT DL380 GEN10",
"entityType": "COMPUTE",
"entitySerialNum": "1234567",
"entityProductId": "7654321",
"entityManufactureTimestamp": "2023-11-01T00:00:00.000Z",
"locationName": "Somewhere",
"locationId": "00000000-0000-0000-0000-000000000000",
"locationCity": "Boston",
"locationState": "MA",
"locationCountry": "USA",
"tags": [
{
"name": "OS",
"value": "Linux"
}
],
"name": "",
"cost": 100.1234,
"costUsd": null,
"currency": "USD",
"co2eMetricTon": 0.6,
"kwh": 700.1234
}
],
"count": 1,
"offset": 0,
"total": 1
}This call can be filtered using the filter query parameter. Refer to filtering for more details.
This call can also be filtered by tags using the filter-tags query parameter. Refer to Filtering tags for more details.
This call can be provided a currency currency code query parameter to change the returned currency type. Refer to Currency for more details.
Other supported API parameters are sort, offset and limit.
Returned field costUsd is deprecated in favor of cost.
This endpoint is for getting the total aggregated energy usages across all entities for the defined time frame. The start-time and end-time query parameters are required. The start-time and end-time query parameters must be in ISO 8601 time format, for example 2019-10-12T07:20:50.52934852Z.
GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/usage-totals?start-time={{START_TIME}}&end-time={{END_TIME}}'Sample API response:
{
"items": [
{
"type": "sustainability-insight-ctr/totals",
"cost": 100.1234,
"costUsd": null,
"currency": "USD",
"co2eMetricTon": 0.5,
"kwh": 700.1234
}
],
"count": 1
}This example response returns one result ("count": 1) and returns the following data:
cost—The estimated energy cost.co2eMetricTon—Carbon dioxide equivalent estimated in metric tons.kwh—Energy consumption in kilowatts per hour.currency—The returned cost currency type.
This call can be filtered using the filter query parameter. Refer to filtering for more details.
This call can also be filtered by tags using the filter-tags query parameter. Refer to Filtering tags for more details.
This call can be provided a currency currency code query parameter to change the returned currency type. Refer to Currency for more details.
Returned field costUsd is deprecated in favor of cost.
This endpoint is for getting energy usages across all entities grouped by time bucket for the defined time frame. The start-time, end-time, and interval query parameters are required. Behavior is non-deterministic if the time range does not divide evenly by your selected interval.
GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/usage-series?start-time={{START_TIME}}&end-time={{END_TIME}}&interval={{INTERVAL}}'Sample API response:
{
"items": [
{
"id": "2024-01-18T00:00:00.000Z",
"type": "sustainability-insight-ctr/timeseries",
"timeBucket": "2024-01-18T00:00:00.000Z",
"cost": 0,
"currency": "USD",
"costUsd": null,
"co2eMetricTon": 0,
"kwh": 0
},
{
"id": "2024-01-19T00:00:00.000Z",
"type": "sustainability-insight-ctr/timeseries",
"timeBucket": "2024-01-19T00:00:00.000Z",
"cost": 50.01234,
"currency": "USD",
"costUsd": null,
"co2eMetricTon": 0.25,
"kwh": 345.321
}
],
"count": 2
}This example response returns two results ("count": 2).
The interval query parameter must be of the format "integer unit". Valid units are day(s), hour(s), week(s), month(s), and year(s), for example, 1 day, 2 hours, 6 week, 18 month, and 3 year. The example response shows an interval of 1 day as the "id:" and "timeBucket" increase by one day (2024-01-18T00:00:00.000Z and 2024-01-19T00:00:00.000Z).
timeBucket—A time bucket is a feature of time series analysis and forecasting. It is the time interval between successive measurements or values. In the example response, thetimeBucketinterval is1 dayand the measures forcostUsd.co2eMetricTon, andkwhare daily totals.cost—The estimated energy cost.co2eMetricTon—Carbon dioxide equivalent estimated in metric tons.kwh—Energy consumption in kilowatts per hour.currency—The returned cost currency type.
This call can be filtered using the filter query parameter. Refer to filtering for more details.
This call can also be filtered by tags using the filter-tags query parameter. Refer to Filtering tags for more details.
This call can be provided a currency currency code query parameter to change the returned currency type. Refer to Currency for more details.
Returned field costUsd is deprecated in favor of cost.
Run the below API call to get public cloud sustainability data related to your workspace. The start-time and end-time query parameters are required. The start-time and end-time query parameters must be in ISO 8601 format, for example 2019-10-12T07:20:50.529Z.
GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/usage-by-entity?start-time={{START_TIME}}&end-time={{END_TIME}}&offset=0'Sample API response:
{
"items": [
{
"id": "COMPUTE1234567",
"type": "sustainability-insight-ctr/cloud-entities",
"serviceProvider": "aws",
"serviceName": "s3",
"serviceRegion": "us-east",
"serviceAccount": "123456789012",
"name": "",
"co2eMetricTon": 0.6
}
],
"count": 1,
"offset": 0,
"total": 1
}This call can be filtered using the filter query parameter. Refer to filtering for more details.
Other supported API parameters are sort, offset, and limit.
This endpoint is for getting the total aggregated public cloud sustainability data across all entities for the defined time frame. The start-time and end-time query parameters are required. The start-time and end-time query parameters must be in ISO 8601 time format, for example 2019-10-12T07:20:50.52934852Z.
GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/usage-totals?start-time={{START_TIME}}&end-time={{END_TIME}}'Sample API response:
{
"items": [
{
"type": "sustainability-insight-ctr/cloud-totals",
"co2eMetricTon": 0.5
}
],
"count": 1
}This example response returns one result ("count": 1) and returns the following data:
co2eMetricTon—Carbon dioxide equivalent estimated in metric tons.
This call can be filtered using the filter query parameter. Refer to filtering for more details.
This endpoint is for getting public cloud sustainability data across all entities grouped by time bucket for the defined time frame. The start-time, end-time, and interval query parameters are required. Behavior is non-deterministic if the time range does not divide evenly by your selected interval.
GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/cloud-usage-series?start-time={{START_TIME}}&end-time={{END_TIME}}&interval={{INTERVAL}}'Sample API response:
{
"items": [
{
"id": "2024-01-01T00:00:00.000Z",
"type": "sustainability-insight-ctr/cloud-timeseries",
"timeBucket": "2024-01-01T00:00:00.000Z",
"co2eMetricTon": 0
},
{
"id": "2024-02-01T00:00:00.000Z",
"type": "sustainability-insight-ctr/cloud-timeseries",
"timeBucket": "2024-02-01T00:00:00.000Z",
"co2eMetricTon": 6.25
}
],
"count": 2
}This example response returns two results ("count": 2).
The interval query parameter must be of the format "integer unit". Valid units are hour, hours, day, days, week, weeks, month, months, year, and years, for example, 1 day, 2 hours, 6 week, 18 month, and 3 year. The example response shows an interval of 1 month as the "id:" and "timeBucket" increase by one day (2024-01-01T00:00:00.000Z and 2024-02-01T00:00:00.000Z).
timeBucket—A time bucket is a feature of time series analysis and forecasting. It is the time interval between successive measurements or values. In the example response, thetimeBucketinterval is1 dayand the measures forcostUsd.co2eMetricTon, andkwhare daily totals.co2eMetricTon—Carbon dioxide equivalent estimated in metric tons.
This call can be filtered using the filter query parameter. Refer to filtering for more details.
This endpoint is for getting previously defined cost and CO2 coefficients.
GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/coefficients'Sample API response:
{
"items": [
{
"id": "00000000-0000-0000-0000-0000000000000",
"type": "sustainability-insight-ctr/coefficient",
"associatedLocation": {
"locationId": "00000000-0000-0000-0000-000000000000",
"locationName": "Denver, CO",
"resourceUri": "/locations/v1beta1/locations/00000000-0000-0000-0000-0000000000000"
},
"startTime": "2024-01-01T00:00:00.000Z",
"co2eGramsPerKwh": 0.5,
"costUsdPerKwh": null,
"costPerKwh": 0.5,
"currency": "USD",
"generation": 0,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-02-01T00:00:00.000Z"
}
],
"count": 1,
"offset": 0,
"total": 1
}
This call can be filtered using the filter query parameter. The only field available to filter on is locationId. Refer to filtering for more details.
This call can also be filtered by tags using the filter-tags query parameter. Refer to Filtering tags for more details.
This call can be provided a currency currency code query parameter to change the returned currency type. Refer to Currency for more details.
Other supported API parameters are offset and limit.
Returned field costUsdPerKwh is deprecated in favor of costPerKwh.
This endpoint is for setting cost and CO2 coefficients for your workspace. This endpoint requires the HPE Sustainability Insight Center Administrator Role. You must provide a location URI as locationId. If you exclude co2eGramsPerKwh or costPerKwh, its behavior is the same as including it with useCurrent set to true.
useDefault- Set to true if you want to use the default value determined by HPE. This cannot be true ifuseCurrentis true.useCurrent- Set to true if you want to keep whatever was previously set for this coefficient. This cannot be true ifuseDefaultis true.value- A floating point number to be used as the coefficient starting the next day, as long asuseDefaultanduseCurrentare both false.currency- In the case of thecostPerKwh, you can provide a currency code to specify the type of cost. Refer to Currency for more details.
Input field costUsdPerKwh is deprecated in favor of costPerKwh.
POST '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/coefficients'Sample payload:
{
"locationId": "/locations/v1beta1/locations/00000000-0000-0000-0000-0000000000000",
"co2eGramsPerKwh": {
"useDefault": false,
"useCurrent": false,
"value": 0.1
},
"costUsdPerKwh": null,
"costPerKwh": {
"useDefault": false,
"useCurrent": false,
"value": 0.1,
"currencyCode": "USD"
}
}If this POST call succeeds, the API returns a 201 Created response with the created coefficient. This response contains the exact startTime that the coefficient will begin taking effect. Here is an example:
{
"id": "00000000-0000-0000-0000-0000000000000",
"type": "sustainability-insight-ctr/coefficient",
"associatedLocation": {
"locationId": "00000000-0000-0000-0000-000000000000",
"locationName": "Denver, CO",
"resourceUri": "/locations/v1beta1/locations/00000000-0000-0000-0000-0000000000000"
},
"startTime": "2024-01-02T00:00:00.000Z",
"co2eGramsPerKwh": 0.5,
"costUsdPerKwh": null,
"costPerKwh": 0.5,
"currency": {
"currencyCode": "USD",
"currencyName": "United States Dollar"
},
"generation": 0,
"createdAt": "2024-01-01T12:00:00.000Z",
"updatedAt": "2024-01-01T12:00:00.000Z"
}Returned field costUsdPerKwh is deprecated in favor of costPerKwh.
This endpoint is for getting a single cost and CO2 coefficient.
GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/coefficients/00000000-0000-0000-0000-0000000000000'Sample API response:
{
"id": "00000000-0000-0000-0000-0000000000000",
"type": "sustainability-insight-ctr/coefficient",
"associatedLocation": {
"locationId": "00000000-0000-0000-0000-000000000000",
"locationName": "Denver, CO",
"resourceUri": "/locations/v1beta1/locations/00000000-0000-0000-0000-0000000000000"
},
"startTime": "2024-01-01T00:00:00.000Z",
"co2eGramsPerKwh": 0.5,
"costPerKwh": 0.5,
"currency": {
"currencyCode": "USD",
"currencyName": "United States Dollar"
},
"costUsdPerKwh": null,
"generation": 0,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-02-01T00:00:00.000Z"
}Returned field costUsdPerKwh is deprecated in favor of costPerKwh.
This endpoint is for getting the metadata related to any user uploaded device measurements.
GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/ingests'Sample API response:
{
"items": [
{
"id": "00000000-0000-0000-0000-0000000000000",
"type": "sustainability-insight-ctr/ingest",
"name": "Example Data",
"description": "This data is blah blah blah",
"generation": 0,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-02-01T00:00:00.000Z"
}
],
"count": 1,
"offset": 0,
"total": 1
}This call supports the API parameters offset and limit.
This endpoint is for users to upload their own device measurements to HPE Sustainability Insight Center. The upload must be .csv file and match the HPE Sustainability Insight Center third party data template. You can find the template on the HPE Sustainability Insight Center UI on the Data Configuration > Data Import page. The maximum size allowed for a single upload is 300MB. This endpoint requires the HPE Sustainability Insight Center Administrator Role.
POST '/sustainability-insight-ctr/v1beta1/ingests' -F name="Example Name" -F description="Blah blah blah" -F file=@measurements.csvForm data payload:
name="Example Name"
description="Blah blah blah"
file=@measurements.csvThis endpoint is for getting a metadata on a single device measurement upload.
GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/ingests/00000000-0000-0000-0000-0000000000000'Sample API response:
{
"id": "00000000-0000-0000-0000-0000000000000",
"type": "sustainability-insight-ctr/ingest",
"name": "Example Data",
"description": "This data is blah blah blah",
"generation": 0,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-02-01T00:00:00.000Z"
}This endpoint is for getting the list of all HPE Sustainability Insight Center data sources.
GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/datasources'Sample API response:
{
"items": [
{
"id": "00000000-0000-0000-0000-0000000000000",
"type": "sustainability-insight-ctr/datasources",
"name": "HPE Aruba Central",
"provider": "HPE",
"lastCollectionTime": "2024-05-28T00:00:00.000Z",
"firstCollectionTime": "2024-02-29T00:00:00.000Z",
"generation": 0,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-02-01T00:00:00.000Z"
}
],
"count": 1,
"offset": 0,
"total": 1
}This endpoint is for getting the details of a single data source by id.
GET '{{HOSTNAME}}/sustainability-insight-ctr/v1beta1/datasources/{id}'Sample API response:
{
"id": "00000000-0000-0000-0000-0000000000000",
"type": "sustainability-insight-ctr/datasources",
"name": "HPE Aruba Central",
"provider": "HPE",
"lastCollectionTime": "2024-05-28T00:00:00.000Z",
"firstCollectionTime": "2024-02-29T00:00:00.000Z",
"generation": 0,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-02-01T00:00:00.000Z"
}Filters allow you to limit the entities involved in the REST call. They are specified using the query parameter filter. The following fields can be filtered for regular entities:
entityIdentityMakeentityModelentityTypeentitySerialNumentityProductIdlocationNamelocationIdlocationCitylocationStatelocationCountryname
The following fields can be filtered for cloud entities:
entityIdserviceProviderserviceNameserviceRegionserviceAccountname
Queries will be separated by
and.Queries will have 'equality', 'contains', and 'in' comparison.
Each query must follow the format below for different operators.
key eq 'value'for an 'equality' operation.contains(key, 'value')for a 'contains' operation.key in ('value1', 'value2')for an 'in' operation.
Here is a simple example of filtering energy usage data based on an entity model:
GET <URI>?filter=entityModel eq 'PROLIANT DL380 GEN10'In this example, the API call only returns data from the entities with the model of ProLiant DL380 Gen10.
Property is the name of an attribute in the requested resource type, for example, flag. The property name is always to the left of the operation. Specify nested property names with the / separator.
The following example of the possible filter values use the GET Usage by Entity endpoint.
| Filter | Example |
|---|---|
| Location country | locationCountry eq 'USA' |
| Entity make | entityMake eq 'HPE' |
| Entity model | entityModel eq 'PROLIANT DL380 GEN10' |
| Entity type | entityType eq 'COMPUTE' |
| Location city | locationCity eq 'Boston' |
| Location state | locationState eq 'MA' |
| Entity serial number | entitySerialNum eq '1234567' |
| Entity product ID | entityProductId eq '7654321' |
Operations compare properties against literals, for example, eq. All parameters require the property on the left and the literal on the right.
Examples of operations:
| Operation | Example | Description |
|---|---|---|
| eq | locationCountry eq 'Mexico' | locationCountry equals Mexico |
| in | locationCountry in ('Brazil', 'Germany') | locationCountry must equal one of the literals Brazil or Germany |
A literal is what an operation compares a property to. For a successful matching operation, the data types must match, and the syntax determines the data type of the literals. Since our API only supports string filters at this time, this means the literal must be a string literal. String literals are anything inside 'single quotes'. Due to URL encoding, reserved characters ! # $ & ' ( ) * + , / : ; = ? @ [ ] in string literals must be replaced with percent-encoded equivalents.
The previous section explained queries for filtering on a single property. However, the logical operations enable more elaborate filtering using multiple queries. Currently, filtering supports combining multiple operations using the 'and' operator.
- Require both (and):
entityMake eq 'HPE' and locationCity eq 'Boston'
This filtering is a subset of OData 4.0 filtering.
Similar to filter, the filter-tags query parameter allows you to limit the entities involved in a REST call based on their tags. You can filter based on a tag's key and value, case-insensitive.
Separate multiple tag filter queries with
and.The only comparison available for tag filters is 'equality'.
Each query must follow the format below.
'key' eq 'value'for an 'equality' operation.
Here is a simple example of filtering energy usage data based on an entity model:
GET <URI>?filter-tags='OS' eq 'Linux'In this example, the API call only returns data from the entities tagged with the Linux operating system.
Operations compare tag keys against tag values using the eq equality operation. All parameters require the tag key on the left and the tag value on the right.
Examples of operations:
| Operation | Example | Description |
|---|---|---|
| eq | 'type' eq 'business' | type equals business |
| eq | 'severity' eq 'Escalated' | severity equals escalated |
The type of all tag keys and values is string literal. String literals are anything inside 'single quotes'. Due to URL encoding, reserved characters ! # $ & ' ( ) * + , / : ; = ? @ [ ] in string literals must be replaced with percent-encoded equivalents.
The previous section explained queries for tag filtering on a single tag. However, the logical operations enable more elaborate tag filtering using multiple queries. Currently, tag filtering supports combining multiple operations using the 'and' operator.
- Require both (and):
'type' eq 'business' and 'OS' eq 'Linux'
This filtering is a subset of OData 4.0 filtering.
Several endpoints allow you to specify the currency type for your input values or the currency type for the returned values. Valid values for the currency are case-insensitive, 3-letter currency codes, such as USD for the United States Dollar.
The following table shows all supported currency codes and their expanded name.
| Currency Code | Name |
|---|---|
| THB | Thai Baht |
| CHF | Swiss Franc |
| INR | Indian Rupee |
| EUR | Euro |
| GBP | Pound Sterling |
| NOK | Norwegian Krone |
| USD | US Dollar |
| AUD | Australian Dollar |
| SEK | Swedish Krona |
| HKD | Hong Kong Dollar |
| AED | UAE Dirham |
| NZD | New Zealand Dollar |
| BGN | Bulgarian Lev |
| RON | Romanian Leu |
| CAD | Canadian Dollar |
| UAH | Ukrainian Hryvnia |
| MXN | Mexican Peso |
| KRW | South Korean Won |
| JPY | Japanese Yen |
| TRY | Turkish Lira |
| DKK | Danish Krone |
| PLN | Polish Zloty |
| CZK | Czech Koruna |
| CLP | Chilean Peso |
| CNY | Chinese Yuan |
| ILS | Israeli New Shekel |
| HRK | Croatian Kuna |
| BAM | Convertible Mark |
| TWD | New Taiwan Dollar |
| MYR | Malaysian Ringgit |
At the start of each day, a currency conversion rate is calculated for each currency and used to convert any values collected for that day.