GET /api/v3/savings/task

Get a list of cost avoidance tasks NOTE: does not include cost avoidance tasks created from prior versions of the software

GetSavingsTasksV3 Permissions: Meters (View)
Paginated endpoint — This API returns paginated results. Use the pageNumber and pageSize query parameters to control which page of results is returned. The response includes pagination metadata in the response headers. See the Pagination guide for details.

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.

Query Parameters

Name Description Type Required
filter string (string) Optional
pageSize The number of elements to return in a page integer (int32) Optional
pageNumber The current page number integer (int32) Optional

Filters

Filter Description Type Operators
batchCode Batch Number String equals not equals one of like not like not one of
batchId Integer equals not equals less than between one of greater than less than equal greater than equal not one of
beginDate DateTime equals not equals less than between greater than less than equal greater than equal today yesterday last 7 days last 14 days last 30 days last 60 days last 90 days
budgetVersionId Integer equals not equals less than between one of greater than less than equal greater than equal not one of
exportFileName String equals not equals one of like not like not one of
exportMode Export Mode String equals not equals one of like not like not one of
fullName Full Name String equals not equals one of like not like not one of
masterTaskId Integer equals not equals less than between one of greater than less than equal greater than equal not one of
setupSheetAction String equals not equals one of like not like not one of
setupSheetType String equals not equals one of like not like not one of
taskGUID Task GUID String equals not equals one of like not like not one of
taskId Integer equals not equals less than between one of greater than less than equal greater than equal not one of
taskStatus String equals not equals one of like not like not one of

Response Headers

This endpoint returns pagination metadata in the response headers.

Header Type Description
PageNumber integer The current page number (1-based).
PageSize integer The maximum number of items per page.
TotalNumberOfRecords integer The total number of records matching the query across all pages.
TotalPages integer The total number of pages. Increment pageNumber until it equals this value to retrieve all results.

See the Pagination guide for iteration examples and best practices.

Responses

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

Response Body Parameters

Array of:

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 Required (defined) string
dataTypeId Required (defined) integer (int32)
dataTypeInfo 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-03-30",    "costAvoidanceTaskId": 1,    "endDate": "2026-03-30",    "filters": [
      {      "availableOperator": [],      "caption": "string",      "dataFieldId": 1,      "dataType": {},      "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
    }
  }
]
204 No Content The request succeeded. No content is returned in the response body.