GET /api/v202604/eui/goals/topmost/{topmostPlaceId}

Retrieves all EUI goals under and including the specified topmost place

GetEUIGoalsForTopmostV202604 Permissions: BuildingsAndOrganizations (View)

Use this endpoint to get EUI goals for an entire organizational subtree at once. Returns goals for the specified place and all descendant places that have goals configured.

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.

Path Parameters

Name	Description	Type	Required
topmostPlaceId	Unique numeric identifier of the topmost place	integer (int32)	Required

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
createdBy	Created By	Integer	one of
status	EUI Goal Status	String	equals
targetYear	Target Year	Integer	one of
topmostPlaceCode	Topmost Place Code	String	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:

EUIGoalResponseV202604

Property

Description

Type

baseYear

The base year for this EUI goal, which is used as the basis for calculating the EUI reduction percentage.

integer (int32)

baseYearEUI

The EUI for this goal’s place in the selected base year. Null if the EUI is not available for the base year.

number (double)

baseYearUse

The total energy use for this goal’s place in the selected base year. Null if the energy use is not available for the base year.

number (double)

createdBy

UserChild

UserChild properties

Property	Description	Type
fullName	The user’s full name	string
userCode	The user code	string
userId	The user identifier	integer (int32)

createdByWatts

Gets or sets a value indicating whether the goal was created by Watts.

boolean

energyProjectCount

The number of energy projects associated with this goal’s place.

integer (int32)

euiGoalId

The identifier for the EUI goal.

integer (int32)

milestones

A list of milestones associated with this EUI goal.

EUIGoalMilestoneResponseV202604[]

EUIGoalMilestoneResponseV202604 properties

Property	Description	Type
actualEUI	The actual EUI achieved for this milestone’s year. Null if the milestone’s target year is either the current year or in the future.	number (double)
actualEUIReductionPercentage	The actual percentage EUI reduction achieved for this milestone’s year. Null if the milestone’s target year is either the current year or in the future.	number (double)
euiGoalMilestoneId	The identifier for the EUI goal milestone.	integer (int32)
targetEUI	The target EUI for this milestone. Null if the EUI is not available for the base year.	number (double)
targetReductionPercentage	A percent value that represents the target EUI reduction for the target year.	number (double)
targetYear	The target year this milestone represents.	integer (int32)

place

EUIGoalPlaceDataV202604

EUIGoalPlaceDataV202604 properties

Property

Description

Type

buildDate

string (date-time)

isDataRolledUp

Tells whether or not the place’s data is rolled up to its parents.

boolean

parent

PlaceChild

PlaceChild properties

Property

Description

Type

isDataRolledUp

Tells whether or not the place’s data is rolled up to its parents.

boolean

placeCode

The place code

string

placeId

The place identifier

integer (int32)

placeInfo

The place info

string

placeType

PlaceTypeResponse

PlaceTypeResponse properties

Property

Description

Type

icon

Icon

Icon properties

Property	Description	Type
code	The icon code Must be between 0 and 64 characters Required when Color is set	string
color	The icon color Must be between 0 and 32 characters Required when Code is set	string

isSystemPlaceType

Flag to indicate if the place type is a system-level place type

boolean

placeEntityType

PlaceEntityTypeV202406

PlaceEntityTypeV202406 properties

Property	Description	Type
placeEntityTypeId	The place entity type identifier	integer (int32)
placeEntityTypeInfo	The place entity type name	string

placeTypeCode

The place type code

string

placeTypeId

The place type identifier

integer (int32)

placeTypeInfo

The place type info

string

structure

Indicates if the place is a structure

boolean

placeCode

The place code

string

placeId

The place identifier

integer (int32)

placeInfo

The place info

string

placeSize

PlaceSizeChild

PlaceSizeChild properties

Property	Description	Type
beginDate	The effective start date for this place size record	string (date-time)
endDate	The effective end date for this place size record	string (date-time)
placeSizeId	The identifier for this PlaceSize record	integer (int32)
unitCode	The code for the unit this place size is measured in Must be between 0 and 16 characters Must be between 0 and 16 characters	string
unitId	The identifier for the unit this place size is measured in	integer (int32)
unitInfo	The name of the unit this place size is measured in Must be between 0 and 32 characters Must be between 0 and 32 characters	string
value	The value of the current place size record	number (double)

placeType

PlaceTypeResponse

PlaceTypeResponse properties

Property

Description

Type

icon

Icon

Icon properties

Property	Description	Type
code	The icon code Must be between 0 and 64 characters Required when Color is set	string
color	The icon color Must be between 0 and 32 characters Required when Code is set	string

isSystemPlaceType

Flag to indicate if the place type is a system-level place type

boolean

placeEntityType

PlaceEntityTypeV202406

PlaceEntityTypeV202406 properties

Property	Description	Type
placeEntityTypeId	The place entity type identifier	integer (int32)
placeEntityTypeInfo	The place entity type name	string

placeTypeCode

The place type code

string

placeTypeId

The place type identifier

integer (int32)

placeTypeInfo

The place type info

string

structure

Indicates if the place is a structure

boolean

primaryUse

PrimaryUseChild

PrimaryUseChild properties

Property	Description	Type
primaryUseCode		string
primaryUseId		integer (int32)
primaryUseInfo		string

wattsCreatedDate

Gets or sets the date and time when the goal was created by Watts.

string (date-time)

wattsModifiedDate

Gets or sets the date and time when the goal was last modified by Watts.

string (date-time)

Example Response application/json

[
  {    "baseYear": 1,    "baseYearEUI": 1.0,    "baseYearUse": 1.0,    "createdBy": {      "fullName": "string",      "userCode": "string",      "userId": 1
    },    "createdByWatts": false,    "energyProjectCount": 1,    "euiGoalId": 1,    "milestones": [
      {      "actualEUI": 1.0,      "actualEUIReductionPercentage": 1.0,      "euiGoalMilestoneId": 1,      "targetEUI": 1.0,      "targetReductionPercentage": 1.0,      "targetYear": 1
    }
    ],    "place": {      "buildDate": "2026-06-18",      "isDataRolledUp": false,      "parent": {},      "placeCode": "string",      "placeId": 1,      "placeInfo": "string",      "placeSize": {},      "placeType": {},      "primaryUse": {}
    },    "wattsCreatedDate": "2026-06-18",    "wattsModifiedDate": "2026-06-18"
  }
]