POST /api/v3/savings/exec

Calculates cost avoidance savings for meters matching filter criteria

CalculateSavingsV3 Permissions: SavingsEngine (Run)
Use this endpoint to run the savings processor for multiple meters. Filters determine which meters are processed. Bill selection options control which bills are recalculated. Optionally skip one or all special adjustment categories. Runs asynchronously as a background task. Use GET /task/{guid} to check progress. Requires Savings Engine Run permission.

Request Headers

Header Value Required Description
ECI-ApiKey string Yes Your API key. See Authentication.
Content-Type application/json Yes All requests must specify JSON content type, including the request body.

Request Body

CalculateSavingsRequest
Property Description Type
billSelectionOption

Determines which option will be used to select the bills for this instance of the cost avoidance processor to process

  • “AllBills” means all bills will be processed
  • “ModifiedOrNotProcessed” means only new bills or bills which have been modified since the last time cost avoidance was run will be processed
  • “BillingPeriod” means that only bills with a billing period which is greater than or equal to the provided billing period will be processed One of ‘AllBills’, ‘ModifiedOrNotProcessed’, ‘BillingPeriod’
 string
billingPeriod When BillSelectionOption is ‘BillingPeriod’, this defines the billing period to be used to target bills for processing Valid billing period between 190001 and 300001 NULL Valid Required when BillSelectionOption is set to BillingPeriod, case sensitive. integer (int32)
filters Filter criteria which determine the meters whose savings will be reprocessed FilterEdit[]
FilterEdit properties
Property Description Type
fieldId Data field ID for the filter Required integer (int32)
operator Filter operator expressed as a string (e.g. “equals”) Required string
value Filter value string
skipSpecialAdjustmentOption Allow the user to optionally exclude one or all special adjustments One of ‘SkipAll’, ‘SkipOne’, ‘SkipNone’ string
specialAdjustmentTypeIdToIgnore During cost avoidance processing, the special adjustment having the provided special adjustment type ID will not be applied (only if SkipSpecialAdjustmentOption = “SkipOne”) Required when SkipSpecialAdjustmentOption is set to SkipOne, case sensitive. integer (int32)
Example Request Body application/json 
{  "billSelectionOption": "string",  "billingPeriod": 1,  "filters": [
    {    "fieldId": 1,    "operator": "string",    "value": "string"
  }
  ],  "skipSpecialAdjustmentOption": "string",  "specialAdjustmentTypeIdToIgnore": 1
}

Responses

200 OK The request succeeded and the response body contains the requested data.

Response Body Parameters

CostAvoidanceTask
Property Description Type
baselineLog BaselineLog
BaselineLog properties
Property Description Type
errorCount Number of meters processed with errors integer (int32)
numberOfMeters Number of meters to process integer (int32)
status The status of baseline processing string
successCount Number of meters successfully processed integer (int32)
warningCount Number of meters processed with warning integer (int32)
beginDate The date and time the task began string (date-time)
costAvoidanceTaskId The task ID integer (int32)
endDate The date and time the task finished. If the task is not finished, endDate will have no value string (date-time)
filters The task’s filters FilterResponse[]
FilterResponse properties
Property Description Type
availableOperator The list of available operators Required (defined) string[]
caption The caption of the filter Required (defined) string
dataFieldId The datafield identifier Required (defined) integer (int32)
dataType DataTypeResponse
DataTypeResponse properties
Property Description Type
dataTypeCode The data type code/short name Required (defined) string
dataTypeId The unique identifier for the data type (e.g., 1=boolean, 2=integer, 3=string, 4=double, 6=date, 12=select list, 13=URL) Required (defined) integer (int32)
dataTypeInfo The data type display name/description Required (defined) string
fieldId The field identifier Required (defined) integer (int32)
hidden Indicates if the filter is hidden Required (defined) boolean
operator The operator Required (defined) string
queryParameterName The Query parameter name Required (defined) string
recommended Indicates if the filter is recommended Required (defined) boolean
required Indicates if the filter is required boolean
value The value of the filter Required (defined) string
hasAttachments Indicates whether or not the task has an output log available for download boolean
message If there was a catastrophic error during task processing, it will go here string
reason

The reason for the cost avoidance task. Will be one of the following:

  • ResetBaseline
  • SavedAndReprocessedMeter
  • ProcessSavings
  • SpecialAdjustmentAddedEditedRemoved
  • SpecialAdjustmentAddedEditedRemovedSetupSheet
  • MeterCostAvoidanceSettingsGloballyUpdated
  • AucRangeModified
  • OtherSavingsAddedEdited
  • OtherSavingsAddedEditedSetupSheet
 string
savingsLog SavingsLog
SavingsLog properties
Property Description Type
errorCount Number of meters processed with errors integer (int32)
numberOfMeters Number of meters to process integer (int32)
status The status of savings processing string
successCount Number of meters successfully processed integer (int32)
warningCount Number of bills processed that have warnings across all meters processed A bill has a “warning” if it had 1) incomplete weather data or 2) exceeded the average unit cost range set for its commodity integer (int32)
settings CostAvoidanceSettings
CostAvoidanceSettings properties
Property Description Type
billSelectionOption

For savings calculation, indicates which bills should have been processed Will be empty unless Reason is “ProcessSavings” Possible values:

  • “AllBills” means all bills were processed
  • “ModifiedOrNotProcessed” means only new bills or bills which have been modified since the last time cost avoidance was run have been processed
  • “BillingPeriod” means that only bills with a billing period which is greater than or equal to the MinimumBillingPeriod have been processed
 string
ignoredSpecialAdjustmentType Defines handling of meter special adjustments during Cost Avoidance processing. Can be either of two static values OR the special adjustment category that the user chose to skip. Will be empty unless Reason is “ProcessSavings” Possible static values: “NONE” - no special adjustment categories were skipped “ALL” - all special adjustment categories were skipped string
ignoredWeatherAdjustments Indicates if weather adjustments were ignored when the baseline processor was run Will be null unless Reason is “ResetBaseline” boolean
minimumBillingPeriod Only bills with a billing period greater than or equal to this value were included in Cost Avoidance processing Will be null unless BillSelectionOption is “BillingPeriod” and Reason is “ProcessSavings” integer (int32)
skippedMultiAccountIfBillsMissing Indicates if the Cost Avoidance processor skipped processing meters with multiple accounts if one of the bills was missing Will be empty unless Reason is “ProcessSavings” boolean
status

The status of the cost avoidance task. Will be one of the following:

  • Processing
  • Complete
  • Error
 string
taskGUId The task GUID string (uuid)
taskNote Notes added to the cost avoidance task by the user string
taskType TaskType
TaskType properties
Property Description Type
taskTypeCode The code for task type string
taskTypeId The task type identifier integer (int32)
taskTypeInfo The task type information string
user UserChild
UserChild properties
Property Description Type
fullName The user’s full name string
userCode The user code string
userId The user identifier integer (int32)
Example Response application/json 
{  "baselineLog": {    "errorCount": 1,    "numberOfMeters": 1,    "status": "string",    "successCount": 1,    "warningCount": 1
  },  "beginDate": "2026-06-29",  "costAvoidanceTaskId": 1,  "endDate": "2026-06-29",  "filters": [
    {    "availableOperator": [
      "string"
    ],    "caption": "string",    "dataFieldId": 1,    "dataType": {      "dataTypeCode": "string",      "dataTypeId": 1,      "dataTypeInfo": "string"
    },    "fieldId": 1,    "hidden": false,    "operator": "string",    "queryParameterName": "string",    "recommended": false,    "required": false,    "value": "string"
  }
  ],  "hasAttachments": false,  "message": "string",  "reason": "string",  "savingsLog": {    "errorCount": 1,    "numberOfMeters": 1,    "status": "string",    "successCount": 1,    "warningCount": 1
  },  "settings": {    "billSelectionOption": "string",    "ignoredSpecialAdjustmentType": "string",    "ignoredWeatherAdjustments": false,    "minimumBillingPeriod": 1,    "skippedMultiAccountIfBillsMissing": false
  },  "status": "string",  "taskGUId": "string",  "taskNote": "string",  "taskType": {    "taskTypeCode": "string",    "taskTypeId": 1,    "taskTypeInfo": "string"
  },  "user": {    "fullName": "string",    "userCode": "string",    "userId": 1
  }
}