Get Monthly Utility Consumption Action

Query Customer Data Platform calculated insights to retrieve monthly utility consumption data for trend analysis and recommendations.

This action is available in API version 60.0 and later.

Special Access Rules

The Get Monthly Utility Consumption action is available in Enterprise and Unlimited Editions with Energy and Utilities Cloud. The org must have Data Cloud (Customer Data Platform) enabled with the relevant calculated insight configured.

Supported REST HTTP Methods

URI: /services/data/v60.0/actions/standard/getMonthlyUtilityConsumption

Formats: JSON, XML

HTTP Methods: GET

Authentication: Authorization: Bearer TOKEN

Where TOKEN is a variable.

Inputs

Input	Type	Description
`dataSpaceApiName`	string	Optional. API name of the Data Cloud data space. Defaults to `Default`.
`calculatedInsightApiName`	string	Required. API name of the calculated insight that supplies consumption data.
`consumptionRequestFilter`	Object	Required. Filter criteria for the consumption query. Contains these fields. `servicePointExternalId` (string, required): External ID of the service point. `monthLimit` (integer, optional): Number of months of consumption data to retrieve. `completeMonthsOnly` (boolean, optional): When `true`, includes only complete calendar months.

Outputs

Output	Type	Description
`consumptionDetails`	Object[]	List of monthly consumption records. Each item contains these fields. `month` (string): Month identifier for the consumption record. `consumption` (number): Consumption value for the month. `uom` (string): Unit of measure for the consumption value.

Example

POST

This sample request is for the Get Monthly Utility Consumption action.

1{
2  "inputs": [
3    {
4      "calculatedInsightApiName": "MonthlyConsumption__cio",
5      "consumptionRequestFilter": {
6        "servicePointExternalId": "SP456",
7        "monthLimit": 3,
8        "completeMonthsOnly": true
9      }
10    }
11  ]
12}

This sample response is for the Get Monthly Utility Consumption action.

1[
2  {
3    "actionName": "getMonthlyUtilityConsumption",
4    "errors": null,
5    "invocationId": null,
6    "isSuccess": true,
7    "outputValues": {
8      "consumptionDetails": [
9        {
10          "month": "2026-04",
11          "consumption": 980,
12          "uom": "kWh"
13        },
14        {
15          "month": "2026-05",
16          "consumption": 1000,
17          "uom": "kWh"
18        }
19      ]
20    },
21    "sortOrder": -1,
22    "version": 1
23  }
24]