POST /monitored-entity — List Monitored Entities

Like Variable List, this is a POST request with a JSON body rather than a GET with query parameters. Unlike Get Monitored Entity (GET /monitored-entity/{id}), there’s no id segment here — the same base path, /monitored-entity, is overloaded across both a POST for search/list and a GET .../{id} for a single record.

Ids below follow the same convention used on Variable List and Filter For List: ids identifying one specific real-world record are shown as anonymized 8-character placeholders, reusing the same id already assigned on those pages wherever the name matches (for example, Oberlin College is 0c8a44f7 everywhere). Catalog-style ids that are already documented as small integers elsewhere (buildingType) are kept as-is.

Endpoint

POST /monitored-entity

Query parameters

Parameter	Description
`page`	Page number to retrieve (1-indexed).
`per_page`	Number of results per page. Default `25`. Accepts `25`, `50`, or `100` — `100` is the documented maximum.
`orderColumn`	Column to sort by (for example `name`). Overrides the response’s `defaultOrderColumn` when present. Which columns are valid beyond `name` isn’t documented.
`order`	Sort direction — `asc` or `desc`. Only meaningful together with `orderColumn`.

Request body

Filters mirror the facet ids returned by GET /monitored-entity/get-filters:

Field	Type	Description
`organizations`	array of string	Organization ids to filter by — see Organizations.
`buildingType`	array of integer	Metered entity type filter — same ids as the `buildingType` facet.
`tags`	array of string	Tag ids to filter by. Tags are scoped per organization (see Filter For List), so a tag id is only meaningful together with the organization it belongs to — passing tag ids from more than one organization in the same request isn’t documented.
`showHiddenMeteredEntities`	boolean	Whether to include entities that would otherwise be hidden.

Open — not fully decided: whether these filters are required vs. optional, what an empty/omitted filter means, and the exact behavior of showHiddenMeteredEntities when false or omitted, aren’t confirmed — the same open questions as Variable List’s equivalent filters.

Example request

curl -X POST "https://api.communityhub.cloud/dh/public/v1/monitored-entity?order=desc&orderColumn=name&page=1&per_page=25" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "organizations": ["0c8a44f7", "9d2e77b4"],
    "buildingType": [1, 2],
    "tags": ["60f10962", "95f52d63"],
    "showHiddenMeteredEntities": true
  }'

organizations here is ["0c8a44f7", "9d2e77b4"] — Oberlin College and City of Oberlin. tags is ["60f10962", "95f52d63"] — Administrative and Academic, both from Oberlin College’s own tag list (see Filter For List). Since tags are org-scoped, mixing tag ids from an organization not present in organizations isn’t a documented scenario.

Response shape

{
  "data": [],
  "defaultOrderColumn": [],
  "pagination": {
    "total_records": 0,
    "total_perpage": 0,
    "total_page": 0,
    "current_page": 0,
    "next_page": null,
    "previous_page": null
  }
}

Top-level fields

Field	Type	Description
`data`	array	Matching monitored entities — see Monitored entity object below.
`defaultOrderColumn`	array	Default sort applied when no explicit sort is requested. Empty in this example; on Variable List the equivalent field is a populated `[column, direction]` tuple — whether that’s a real difference or just an artifact of this particular (empty) example isn’t confirmed.
`pagination`	object	Pagination metadata — same shape as Variable List, though every value in this example is `0`/`null` because the query matched no records.

Monitored entity object

Example item from data:

{
  "id": "f1cd780c",
  "name": "AJLC Annex",
  "type": {
    "id": 0,
    "name": "Building"
  },
  "orgId": "0c8a44f7",
  "meta": {
    "area": "3712",
    "type": "N/A",
    "address": "Elm St. 44074 USA",
    "location": {
      "address": "Elm St.",
      "country": "USA",
      "pincode": "44074"
    },
    "coverImageUrl": "https://communityhubstorage.cloud/ch-data-hub/oberlin/data-hub/ajlc-annex.jpeg",
    "average_occupancy": "35",
    "thumbnailImageUrl": "https://communityhubstorage.cloud/ch-data-hub/oberlin/data-hub/ajlc-annex.jpeg",
    "coverImageOriginal": "https://communityhubstorage.cloud/ch-data-hub/oberlin/data-hub/ajlc-annex.jpeg",
    "defaultDashboardId": "f1ce526d",
    "defaultDashboardLink": "https://oberlin.communityhub.cloud/dh-public/ops/dashboard/f1ce526d",
    "includeInNewDashboard": true,
    "defaultVariablesData": {
      "1": {
        "id": "e1b7a6bc",
        "name": "Electricity Use",
        "type": "Electricity",
        "units": "kW",
        "isDisabled": false,
        "resourceId": "877f50fe",
        "binPosition": 3,
        "currentUsage": 1.32
      },
      "7": {
        "id": "613ce478",
        "name": "Gas Usage",
        "type": "Natural Gas",
        "units": "hcf/hr",
        "isDisabled": false,
        "resourceId": "1d1d1bcb",
        "binPosition": 1,
        "currentUsage": 0
      }
    }
  },
  "description": "AJLC Annex",
  "scope": "whole_organization",
  "visibilityStatus": true,
  "organization": {
    "id": "0c8a44f7",
    "name": "Oberlin College"
  },
  "variables": [
    {
      "id": "331349e7",
      "name": "Reactive Electricity",
      "variableType": {
        "id": 1,
        "name": "Electricity"
      }
    }
  ],
  "tags": [
    {
      "id": "60f10962",
      "name": "Administrative"
    }
  ]
}

Monitored entity object fields

Field	Type	Description
`id`	string	The monitored entity’s own id — the same id used in Get Monitored Entity and Connected Variables’ `building` filter.
`name`	string	Display name.
`type`	object	Entity type (`id`, `name`) — same ids as the `buildingType` facet.
`orgId`	string	Owning organization’s id — duplicates `organization.id` below.
`meta`	object	Entity metadata — see fields below. Structurally similar to the metered-entity metadata described in Core Concepts (area, occupancy, address, default dashboard, default variables), though the field names here don’t match that page’s exactly (for example `area` here vs. “Total Area” there) — not confirmed whether this is the same underlying data.
`description`	string	Free-text description — identical to `name` in this example; whether that’s always true isn’t confirmed.
`scope`	string	A bare string here (`whole_organization`), unlike the `{ id, name }` object shape `scope` takes on a Variable List variable — these are two different fields that happen to share a name.
`visibilityStatus`	boolean	Purpose not documented, same as on the variable object.
`organization`	object	Owning organization (`id`, `name`).
`variables`	array	Variables belonging to this entity, in an abbreviated form (`id`, `name`, `variableType`) — for full variable detail, look each one up via Variable List filtered by this entity’s id, or Get Variable Data using its `dataHubId`.
`tags`	array	This entity’s tags (`id`, `name`) — same tag ids as the org-scoped `tags` facet on Filter For List.

`meta` fields

Field	Type	Description
`area`	string	Matches “Total Area” from Core Concepts, as a string rather than a number. Units are square feet (not included in the value itself — `"3712"` means 3,712 sq. ft.).
`type`	string	A different field from the top-level `type` object above, despite the identical name — here it’s a bare string (`"N/A"` in this example). Meaning and possible values aren’t documented.
`address`	string	Full address as a single string.
`location`	object	Structured address (`address`, `country`, `pincode`) — partially duplicates the flat `address` field above.
`coverImageUrl`, `thumbnailImageUrl`, `coverImageOriginal`	string	Image URLs. Relationship between the three (whether thumbnail/cover are generated from original, or independently uploaded) isn’t documented.
`average_occupancy`	string	Matches “Average Occupancy” from Core Concepts, as a string.
`defaultDashboardId`	string	The entity’s default dashboard id, embedded in `defaultDashboardLink`.
`defaultDashboardLink`	string	Full URL to the default dashboard.
`includeInNewDashboard`	boolean	Purpose not documented.
`defaultVariablesData`	object	Keyed by resource id (the same catalog ids as the `resourceType` facet on Filter Options — `1` = Electricity, `7` = Natural Gas), not by an entity or variable id. Each value describes that resource’s default variable — see below.

`defaultVariablesData[resourceId]` fields

Field	Type	Description
`id`	string	The default variable’s own id.
`name`	string	Variable name.
`type`	string	Resource type name (matches the parent key’s resource, e.g. `"Electricity"` for key `1`).
`units`	string	Units for `currentUsage`.
`isDisabled`	boolean	Whether this default variable is disabled.
`resourceId`	string	See the warning below — this is presented as an 8-character id here, unlike every other resource-type reference on this page and elsewhere in this API, which use small integers.
`binPosition`	integer	Purpose not documented — possibly display ordering.
`currentUsage`	number	Latest usage value for this default variable.

Open — not fully decided, and one direct inconsistency to flag:

defaultVariablesData is keyed by resource id as a small integer ("1", "7") — consistent with resourceType everywhere else in this API — but each entry’s own resourceId field is shown as an 8-character id instead, per the source example. That means the dictionary key and its own resourceId field don’t share a representation for the same concept. This needs a real answer from whoever owns the spec: is resourceId actually the same integer catalog id as the key (and the example values are placeholders that shouldn’t have been uuid-shaped), or is there a genuinely separate uuid-keyed resource reference this page hasn’t seen elsewhere?
meta.type (a bare string) and the entity’s top-level type (an { id, name } object) share a name but are unrelated fields — easy to confuse when integrating against this response.
Whether tags filtering across organizations is supported, given tags are org-scoped.
The error response shape for invalid filters or pagination isn’t documented.

See Filter For List to discover valid organizations, buildingType, and tags values, Get Monitored Entity to fetch a single entity by the id returned here, and Connected Variables to fetch the full variable list for one of these entities.

Overview

Data Ingestion (Not Available)

Retrieving Data

Webhooks (Not Available)

Sample Code (No SDKs)

POST /monitored-entity — List Monitored Entities

Endpoint

Query parameters

Request body

Example request

Response shape

Top-level fields

Monitored entity object

Monitored entity object fields

`meta` fields

`defaultVariablesData[resourceId]` fields

​Endpoint

​Query parameters

​Request body

​Example request

​Response shape

​Top-level fields

​Monitored entity object

​Monitored entity object fields

meta fields

defaultVariablesData[resourceId] fields

Endpoint

Query parameters

Request body

Example request

Response shape

Top-level fields

Monitored entity object

Monitored entity object fields

`meta` fields

`defaultVariablesData[resourceId]` fields