GET /api/v202608/esaalert

Retrieves a paginated list of threshold alerts

ListThresholdAlertsV202608 Permissions: Meters (View)

Use this endpoint to list existing threshold alerts, optionally narrowed by type, association, or status. AlertType accepts one or more of ‘above/below’, ’total over time’, or ’trend insights’ separated by ‘|’; it defaults to ‘above/below|total over time’ when omitted. Pagination, the total count, and every association/status filter operate on one row per channel association (a channel-less alert counts as a single row) rather than per alert: an alert with several matching channels contributes several rows and can span a page boundary, appearing again on a later page with only the channels that landed there. Its Channels collection in the response only reports the channels that actually matched, not every channel the alert happens to be attached to. ChannelId, ParentPlaceId, and MeterId narrow to a specific channel, a meter beneath a given place, or a specific meter, respectively; each must refer to a record accessible to the caller. AlertStatus matches on each channel’s own enabled flag; an alert with no channels is matched on whether the alert itself is active instead. Results are always limited to meters beneath the calling user’s topmost place, whether or not an association filter is supplied. Rows are ordered alphabetically by meter name (channel-less alerts first), then by alert id and channel id.

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
alertType	Pipe-delimited (’\|’) list of alert types to include. Valid values: ‘above/below’, ’total over time’, ’trend insights’. Defaults to ‘above/below\|total over time’ when not specified.	string	Optional
channelId	Unique identifier of an ESA channel to list alerts for; only that channel is reported on a matching alert. Must be accessible to the caller.	integer (int32)	Optional
parentPlaceId	Unique identifier of a place; only channels on meters beneath this place are reported. Must be accessible to the caller.	integer (int32)	Optional
meterId	Unique identifier of a meter to list alerts for; only that meter’s channel is reported on a matching alert. Must be accessible to the caller.	integer (int32)	Optional
alertStatus	Status of alerts to list. Valid values: ’enabled’, ‘disabled’. Matches rows whose channel has this enabled state (see EsaAlertChannelDTO.Enabled) - an alert with several channels can have some rows match and others not, so only the matching channels are reported for it. An alert with no channels is matched on the response’s own AlertActive flag instead.	string	Optional
pageSize	The number of elements to return in a page	integer (int32)	Optional
pageNumber	The current page number	integer (int32)	Optional

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:

EsaAlertResponse

Property

Description

Type

alertActive

Whether the alert is active.

boolean

alertId

Primary key of the EsaAlert record.

integer (int32)

alertMode

Alert mode. 2 = Manual. Automatic types such as Trend Insights use other values.

integer (int32)

channels

The channels this alert is attached to, and the meter and place each one sits under. An alert can be attached to any number of channels, so this is a collection rather than a single id.

Null and empty mean different things. Null means the endpoint does not supply the association - the create response does not, because the caller supplied the channel ids in the request. Empty means the alert genuinely has no channels attached. On the list endpoint (GET, threshold alerts), this only reports the channels that matched the request’s own filters - not necessarily every channel the alert is attached to. A channel-, meter-, place-, or status filter can each narrow it down to a subset.

EsaAlertChannel[]

EsaAlertChannel properties

Property	Description	Type
channelId	Primary key of the attached EsaChannel.	integer (int32)
enabled	Whether the alert is enabled for this specific channel. Distinct from EsaAlertResponseDTO.AlertActive, which is a single switch for the whole alert across every channel it is attached to - this one can differ per channel. Not enforced during evaluation yet: ThresholdAlertCheckJob currently gates only on AlertActive, so a channel reporting false here still fires today. ECAP-34685 adds the per-channel gate. Until it lands, treat this as configuration state, not as a statement about whether notifications will be raised.	boolean
meterId	The meter the channel’s data point belongs to.	integer (int32)
placeId	The place the channel’s meter sits in - the meter’s own place, not an ancestor. Note the list endpoint’s parentPlaceId filter matches any ancestor place, so this will usually differ from the value a caller filtered by.	integer (int32)

esaAlertSeverityRating

EsaAlertSeverityRating

EsaAlertSeverityRating properties

Property	Description	Type
esaAlertSeverityRatingId	Primary key of the EsaAlertSeverityRating record.	integer (int32)
severityRatingDescription	Human-readable description of the severity rating.	string
severityRatingInfo	Display name for the severity rating (e.g. “Medium”).	string

esaAlertSeverityRatingId

FK to the alert’s EsaAlertSeverityRating. Create assigns Medium.

integer (int32)

esaAlertType

EsaAlertType

EsaAlertType properties

Property	Description	Type
alertTypeDescription	Human-readable description of the alert type’s behaviour.	string
alertTypeInfo	Display name for the alert type (e.g. “Above/Below”).	string
allowAutomatic	Whether alerts of this type can be triggered automatically.	boolean
allowManual	Whether alerts of this type can be created manually.	boolean
canHaveAssignee	Whether alerts of this type support an assignee.	boolean
esaAlertTypeId	Primary key of the EsaAlertType record.	integer (int32)
requiresAssignee	Whether alerts of this type require an assignee.	boolean

esaThresholdAlert

EsaThresholdAlert

EsaThresholdAlert properties

Property	Description	Type
alertMode	Alert mode value (2 = Custom).	integer (int32)
esaAlertId	FK to the parent EsaAlert record.	integer (int32)
esaThresholdAlertId	Primary key of the EsaThresholdAlert record.	integer (int32)
interval	Accumulation window in minutes for ’total over time’ alerts; null for ‘above/below’.	integer (int32)
notificationTriggerCount	Number of consecutive threshold violations before firing (always 1).	integer (int32)
scheduleId	FK to the Schedule used for this alert (24/7 by default).	integer (int32)
triggerValue	The threshold value being monitored.	number (double)
triggerValueType	Direction the threshold is evaluated in.	integer (int32)
unitId	FK to Unit defining the unit of measurement for the threshold.	integer (int32)

unit

EsaAlertUnit

EsaAlertUnit properties

Property

Description

Type

unitCode

Short unit code (e.g. “KWH”).

string

unitDisplayName

Full display name (e.g. “kilowatt-hour”).

string

unitId

Primary key of the Unit record.

integer (int32)

unitInfo

Unit display label (e.g. “kWh”).

string

unitType

EsaAlertUnitType

EsaAlertUnitType properties

Property	Description	Type
unitTypeCode	Short type code (e.g. “Counter”).	string
unitTypeId	Primary key of the UnitType record.	integer (int32)
unitTypeInfo	Display label for the unit type (e.g. “counter”).	string

Example Response application/json

[
  {    "alertActive": false,    "alertId": 1,    "alertMode": 1,    "channels": [
      {      "channelId": 1,      "enabled": false,      "meterId": 1,      "placeId": 1
    }
    ],    "esaAlertSeverityRating": {      "esaAlertSeverityRatingId": 1,      "severityRatingDescription": "string",      "severityRatingInfo": "string"
    },    "esaAlertSeverityRatingId": 1,    "esaAlertType": {      "alertTypeDescription": "string",      "alertTypeInfo": "string",      "allowAutomatic": false,      "allowManual": false,      "canHaveAssignee": false,      "esaAlertTypeId": 1,      "requiresAssignee": false
    },    "esaThresholdAlert": {      "alertMode": 1,      "esaAlertId": 1,      "esaThresholdAlertId": 1,      "interval": 1,      "notificationTriggerCount": 1,      "scheduleId": 1,      "triggerValue": 1.0,      "triggerValueType": 1,      "unitId": 1
    },    "unit": {      "unitCode": "string",      "unitDisplayName": "string",      "unitId": 1,      "unitInfo": "string",      "unitType": {}
    }
  }
]

400 Bad Request The request was malformed or contains invalid parameters. Check the request body and query parameters.

403 Forbidden You do not have permission to access this resource. Check your user role and permissions.