> ## Documentation Index
> Fetch the complete documentation index at: https://docs.communityhub.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# POST /monitored-entity — List Monitored Entities
> Search and paginate monitored entities using the same filters returned by GET /monitored-entity/get-filters, including a hidden-entities toggle.
Like [Variable List](/api-reference/query/variable-list), this is a `POST` request with a JSON body rather than a `GET` with query parameters. Unlike [Get Monitored Entity](/api-reference/query/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](/api-reference/query/variable-list) and [Filter For List](/api-reference/query/monitored-entity-filters): 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
```text theme={null}
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 `id`s returned by [`GET /monitored-entity/get-filters`](/api-reference/query/monitored-entity-filters):
| Field | Type | Description |
| --------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `organizations` | array of string | Organization ids to filter by — see [Organizations](/api-reference/query/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](/api-reference/query/monitored-entity-filters#the-tags-facet-s-nesting)), 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](/api-reference/query/variable-list)'s equivalent filters.
## Example request
```bash theme={null}
curl -X POST "https://api.communityhub.cloud/dh/public/v1/monitored-entity?order=desc&orderColumn=name&page=1&per_page=25" \
-H "Authorization: Bearer " \
-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](/api-reference/query/monitored-entity-filters)). Since tags are org-scoped, mixing tag ids from an organization not present in `organizations` isn't a documented scenario.
## Response shape
```json theme={null}
{
"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](#monitored-entity-object) below. |
| `defaultOrderColumn` | array | Default sort applied when no explicit sort is requested. Empty in this example; on [Variable List](/api-reference/query/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](/api-reference/query/variable-list#top-level-fields), though every value in this example is `0`/`null` because the query matched no records. |
### Monitored entity object
Example item from `data`:
```json theme={null}
{
"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](/api-reference/query/monitored-entity) and [Connected Variables](/api-reference/query/monitored-entity-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](/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](/api-reference/query/variable-list#variable-object) 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](/api-reference/query/variable-list) filtered by this entity's id, or [Get Variable Data](/api-reference/query/run-query) using its `dataHubId`. |
| `tags` | array | This entity's tags (`id`, `name`) — same tag ids as the org-scoped `tags` facet on [Filter For List](/api-reference/query/monitored-entity-filters). |
##### `meta` fields
| Field | Type | Description |
| ---------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `area` | string | Matches "Total Area" from [Core Concepts](/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](/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](/api-reference/query/variable-filters) — `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](/api-reference/query/monitored-entity-filters) to discover valid `organizations`, `buildingType`, and `tags` values, [Get Monitored Entity](/api-reference/query/monitored-entity) to fetch a single entity by the `id` returned here, and [Connected Variables](/api-reference/query/monitored-entity-connected-variables) to fetch the full variable list for one of these entities.