POST /variable/list — List Variables

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 and Filter Options.

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 and Filter For List. 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 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

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 ids returned by GET /variable/get-variable-filter-data and GET /monitored-entity/get-filters:

Field	Type	Description
`organizations`	array of string	Organization ids to filter by — see Organizations.
`building`	array of string	Monitored/metered entity ids to filter by — see Get 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

curl -X POST "https://api.communityhub.cloud/dh/public/v1/variable/list?order=desc&orderColumn=displayName&page=1&per_page=25" \
  -H "Authorization: Bearer <token>" \
  -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

{
  "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 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:

{
  "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.
`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.
`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’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:

curl -X POST "https://api.communityhub.cloud/dh/public/v1/variable/list?page=1&per_page=25" \
  -H "Authorization: Bearer <token>" \
  -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 to look up an entity’s id first, and Filter For List to discover which entities exist within an organization before doing so.

Overview

Data Ingestion (Not Available)

Retrieving Data

Webhooks (Not Available)

Sample Code (No SDKs)

POST /variable/list — List Variables

Endpoint

Query parameters

Request body

Example request

Response shape

Top-level fields

Variable object

Variable object fields

Connected Variables

​Endpoint

​Query parameters

​Request body

​Example request

​Response shape

​Top-level fields

​Pagination fields

​Variable object

​Variable object fields

​Connected Variables

Endpoint

Query parameters

Request body

Example request

Response shape

Top-level fields

Pagination fields

Variable object

Variable object fields

Connected Variables