> ## 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 /variable/list — List Variables
> Search and paginate variables using the same filters returned by GET /variable/get-variable-filter-data, including a hidden-variables toggle.
Unlike every other endpoint in this section, this is a `POST` request with a JSON body rather than a `GET` with query parameters, even though it's a listing/search operation. Treat this as directional pending confirmation, consistent with the open questions already flagged on [Discovery Endpoints](/api-reference/query/saved-queries) and [Filter Options](/api-reference/query/variable-filters).
Ids below are presented two ways, matching how the rest of this documentation treats ids. Catalog/lookup ids that are already documented elsewhere as small integers or fixed strings — `resourceType` (`resource.id`), `buildingType`, `pointType`, `status`, `dataReception`, and unit ids (`sourceUnit.id`, `storageUnit.id`) — are kept as given, since they match the ids already listed on [Filter Options](/api-reference/query/variable-filters) and [Filter For List](/api-reference/query/monitored-entity-filters). Ids that identify one specific real-world record — `organizations`, `building`/`monitoredEntities`, `integrations`, and the variable's own `id` — are shown below as anonymized 8-character placeholders instead of the literal values in the source example, consistent with how [Organizations](/api-reference/query/organizations) ids are presented. Where an organization repeats a name already used on the Organizations page (Oberlin College), the same placeholder id is reused for consistency.
## Endpoint
```text theme={null}
POST /variable/list
```
## 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 `displayName`). Overrides the response's `defaultOrderColumn` when present. Which columns are valid beyond `displayName` 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 /variable/get-variable-filter-data`](/api-reference/query/variable-filters) and [`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). |
| `building` | array of string | Monitored/metered entity ids to filter by — see [Get Monitored Entity](/api-reference/query/monitored-entity). |
| `pointType` | array of string | Variable type filter — same values as the `pointType` facet. |
| `resourceType` | array of integer | Resource type filter — same ids as the `resourceType` facet. |
| `integrations` | array of string | Data source/integration ids to filter by. |
| `buildingType` | array of integer | Metered entity type filter — same ids as the `buildingType` facet. |
| `status` | array of string | Variable status filter — same values as the `status` facet. |
| `dataReception` | array of string | Online/offline filter — same values as the `dataReception` facet. |
| `showHiddenVariables` | boolean | Whether to include variables whose `scope` is `hidden` (see `scope` in the response fields below). |
**Open — not fully decided:** whether any of these filters are required vs. optional, whether an empty or omitted filter means "no filter" or "match nothing," and the exact behavior of `showHiddenVariables` when `false` or omitted, aren't confirmed.
## Example request
```bash theme={null}
curl -X POST "https://api.communityhub.cloud/dh/public/v1/variable/list?order=desc&orderColumn=displayName&page=1&per_page=25" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"organizations": ["0c8a44f7"],
"building": ["7c1e9a44"],
"pointType": ["average-rate"],
"resourceType": [4],
"integrations": ["b2d40e91"],
"buildingType": [0],
"status": ["enabled"],
"dataReception": ["online", "offline"],
"showHiddenVariables": true
}'
```
## Response shape
```json theme={null}
{
"data": [],
"defaultOrderColumn": ["displayName", "asc"],
"pagination": {
"total_records": 0,
"total_perpage": 25,
"total_page": 0,
"current_page": 1,
"next_page": 2,
"previous_page": null
}
}
```
### Top-level fields
| Field | Type | Description |
| -------------------- | ------ | --------------------------------------------------------------------------------------------- |
| `data` | array | Matching variables — see [Variable object](#variable-object) below. |
| `defaultOrderColumn` | tuple | `[column, direction]` describing the default sort applied when no explicit sort is requested. |
| `pagination` | object | Pagination metadata — see below. |
### Pagination fields
| Field | Type | Description |
| --------------- | --------------- | ---------------------------------------------------------- |
| `total_records` | integer | Total number of matching variables across all pages. |
| `total_perpage` | integer | Page size (echoes the `per_page` query parameter). |
| `total_page` | integer | Total number of pages. |
| `current_page` | integer | The page returned by this response. |
| `next_page` | integer or null | Next page number, or `null` if this is the last page. |
| `previous_page` | integer or null | Previous page number, or `null` if this is the first page. |
### Variable object
Example item from `data`:
```json theme={null}
{
"status": "enabled",
"id": "e1a4f902",
"isEnabled": true,
"isRecorded": true,
"variableType": "Average Rate",
"sourceName": "Energy Rate",
"displayName": "Energy Rate",
"lastRecordedData": 0,
"lastRecordedTime": "2026-07-27 00:39",
"lastReceivedUnits": "kBtu/hr",
"resource": { "id": 124, "name": "Cooling" },
"sourceUnit": { "id": 280, "longText": "KiloBTU per hour", "shortText": "kBTU/hr" },
"storageUnit": { "id": 281, "longText": "KiloBTU per hour", "shortText": "kBTU/hr", "processingEqn": "$source_value" },
"metadata": {},
"dataHubId": "$obvius_#001ec6002988_not_set_8f32d",
"localTimezone": "America/New_York",
"dataReception": "online",
"scope": { "id": "hidden", "name": "Hidden" },
"isHistorical": false,
"displayUnit": {},
"consumptionUnit": {},
"description": null,
"isUsed": false,
"visibilityStatus": false,
"qdisplayName": "energy rate",
"integration": {
"id": "b2d40e91",
"name": "37 Art Word AAM 75 Art Venturi Datalogger",
"type": "obvius",
"orgId": "0c8a44f7",
"organization": { "id": "0c8a44f7", "name": "Oberlin College" }
},
"tags": [],
"monitoredEntities": [
{ "id": "7c1e9a44", "name": "37 Art Word AAM 75 Art Venturi" },
{ "id": "9d3b0f27", "name": "Heating Cooling Variables Ever-Green" }
],
"organization": { "id": "0c8a44f7", "name": "Oberlin College" },
"integrations": {
"id": "b2d40e91",
"name": "37 Art Word AAM 75 Art Venturi Datalogger",
"type": "obvius",
"orgId": "0c8a44f7",
"organization": { "id": "0c8a44f7", "name": "Oberlin College" }
}
}
```
#### Variable object fields
| Field | Type | Description |
| ------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | string | Same values as the `status` facet (`enabled`, `disabled`, `historical`). |
| `id` | string | The variable's internal id. Distinct from `dataHubId` (see below). |
| `isEnabled` | boolean | Whether the variable is actively recording. |
| `isRecorded` | boolean | Whether readings are being persisted. |
| `variableType` | string | Human-readable variable type (`Average Rate`, `Totalizer`, `Instantaneous Measurement`). |
| `sourceName` | string | Variable name as reported by the data source. |
| `displayName` | string | Variable name shown to users. |
| `lastRecordedData` | number | Last received value. |
| `lastRecordedTime` | string | Timestamp of the last received value. Format/timezone convention not confirmed — appears to be a local, non-ISO 8601 string; compare to `localTimezone`. |
| `lastReceivedUnits` | string | Units of the last received value. |
| `resource` | object | Resource type — `id`/`name` matching the `resourceType` facet from [Filter Options](/api-reference/query/variable-filters). |
| `sourceUnit` | object | Unit as received from the data source (`id`, `longText`, `shortText`). |
| `storageUnit` | object | Unit assigned after processing (`id`, `longText`, `shortText`, `processingEqn`). |
| `metadata` | object | Additional metadata. Empty in every example seen so far — contents not documented. |
| `dataHubId` | string | Stable public identifier for the variable, used in [Get Variable Data](/api-reference/query/run-query). |
| `localTimezone` | string | IANA timezone for the metered/monitored entity this variable belongs to. |
| `dataReception` | string | Same values as the `dataReception` facet (`online`, `offline`). |
| `scope` | object | Visibility scope (`id`/`name`, e.g. `hidden`/"Hidden"). Relationship to `visibilityStatus` and `showHiddenVariables` isn't documented. |
| `isHistorical` | boolean | Whether the variable is historical/deprecated. |
| `displayUnit` | object | Empty in every example seen so far — contents not documented. |
| `consumptionUnit` | object | Empty in every example seen so far — contents not documented. |
| `description` | string or null | Free-text description. |
| `isUsed` | boolean | Purpose not documented. |
| `visibilityStatus` | boolean | Purpose and relationship to `scope` not documented. |
| `qdisplayName` | string | Appears to be a lowercased/normalized form of `displayName`, likely used for search or sort. Not confirmed. |
| `integration` | object | The data source/integration feeding this variable (`id`, `name`, `type`, `orgId`, `organization`). |
| `tags` | array | Labels for grouping. Empty in every example seen so far. |
| `monitoredEntities` | array | The monitored/metered entities this variable is associated with — note a variable can apparently belong to more than one. |
| `organization` | object | The owning organization (`id`, `name`). |
| `integrations` | object | Appears to duplicate `integration` (singular) exactly. Unclear why both are present — possibly one is being phased out in favor of the other. |
**Open — not fully decided:**
* `integration` vs. `integrations`: both fields appear with identical content in the example. Which is authoritative, or whether one is being deprecated, isn't documented.
* `metadata`, `displayUnit`, `consumptionUnit`, `isUsed`, `visibilityStatus`, and `qdisplayName` have no documented meaning beyond what's inferable from their name and the single example provided.
* Which columns are valid for `orderColumn` beyond the `displayName` shown in `defaultOrderColumn` isn't documented.
* The error response shape for invalid filters or pagination isn't documented.
* This example represents `building`/`monitoredEntities` ids as 8-character strings, while [Get Monitored Entity](/api-reference/query/monitored-entity)'s own example path uses a plain numeric id (`250`) — which format is actually correct isn't confirmed; treat both as illustrative until settled.
## Connected Variables
A common use case is fetching every variable connected to one or more specific monitored/metered entities — for example, everything reporting for a single building. Do this by passing the entity's id(s) in the `building` filter:
```bash theme={null}
curl -X POST "https://api.communityhub.cloud/dh/public/v1/variable/list?page=1&per_page=25" \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{
"building": ["7c1e9a44"]
}'
```
This returns every variable whose `monitoredEntities` array includes that id. Omit every other filter to get the full set of connected variables regardless of type, resource, status, or reception state — or combine `building` with any of the other filters (`resourceType`, `status`, `dataReception`, and so on) to narrow further.
Pass more than one id in `building` to fetch variables connected to any of several entities at once (an OR across the listed ids, matching the array-filter pattern used throughout this endpoint's other fields — though this specific behavior isn't independently confirmed).
See [Get Monitored Entity](/api-reference/query/monitored-entity) to look up an entity's id first, and [Filter For List](/api-reference/query/monitored-entity-filters) to discover which entities exist within an organization before doing so.