RelynkLearn
Builder APIAPI referenceConsumption

consumption.buildings (version 1)

Energy, water and waste consumption of buildings from EOS, exactly as the EOS dashboard shows it: per building and carrier (electricity, heating, cooling, gas, water, waste), the sum of the building's building meters (physical and virtual; sub-meters never), per Oslo-time bucket over [from, to), with cost, estimated share, coverage and confidence per bucket and in total. Use this for any building or portfolio consumption, cost or comparison; never add up raw meter points for that. Values are already consumption per hour (not meter readings), in kWh (energy), L (water) or kg (waste); never add different carriers together. null means no data for the bucket, not zero. Omit buildingIds for every building with EOS data. day, week and month buckets need from and to at Oslo midnight; hour buckets up to 62 days, others up to 1100 days, and buildings × carriers × buckets up to 50000.

POST
/consumption.buildings/v1

Authorization

bearer
headerAuthorizationBearer <JWT>

A signed-in Relynk user's access token: OAuth 2.0 authorization code with PKCE at https://auth.relynk.io/authorize and https://auth.relynk.io/oauth/token, with audience https://ai.relynk.io/builder. The caller sees exactly what that user may see.

Query Parameters

tenantId?string

The tenant to read. May be left out when the caller belongs to exactly one tenant; GET /me lists them.

Formatuuid

Request Body

application/json
  1. body
buildingIds?array<>

Building ids (from buildings.list), at most 200; omit for all

Items1 <= items <= 200
carriers?array<>

Only these carriers; omit for all

Items1 <= items <= 7
from*string

Start, inclusive: "YYYY-MM", "YYYY-MM-DD" (Oslo midnight) or ISO 8601 with offset, e.g. "2026-09-01T06:00:00+02:00"

to*string

End, exclusive: "YYYY-MM", "YYYY-MM-DD" (Oslo midnight) or ISO 8601 with offset, e.g. "2026-09-01T06:00:00+02:00"

bucket*string

Bucket size; weeks start on Monday

Value in"hour""day""week""month"
includeSubCategories?boolean

Also split each carrier by what it was consumed for (the waste fraction for waste)

Defaultfalse

Response Body

The function output

application/json
  1. response
timeZone*string
bucket*string
Value in"hour""day""week""month"
from*string
to*string
t*array<string>

Bucket starts, Oslo time with offset; index i matches every array

buildings*array<>
Example Request
curl -X POST 'https://ai.relynk.io/builder/v1/consumption.buildings/v1' \  -H 'Content-Type: application/json' \  -d '{  "from": "string",  "to": "string",  "bucket": "hour"}'
Example Response
{  "timeZone": "Europe/Oslo",  "bucket": "hour",  "from": "string",  "to": "string",  "t": [    "string"  ],  "buildings": [    {      "buildingId": "string",      "buildingName": "string",      "carriers": [        {          "carrier": "electricity",          "unit": "kWh",          "meterCount": 0,          "consumption": [            0          ],          "estimated": [            0          ],          "cost": [            0          ],          "coverage": [            0          ],          "confidence": [            "HIGH"          ],          "sortedShare": [            0          ],          "subCategories": [            {              "label": "string",              "consumption": [                0              ],              "cost": [                0              ],              "total": 0,              "totalCost": 0            }          ],          "total": {            "consumption": 0,            "estimated": 0,            "estimatedShare": 0,            "cost": 0,            "costCoverage": 0,            "coverage": 0,            "confidence": "HIGH",            "sortedShare": 0,            "bucketsWithoutData": 0          },          "overlappingBuildingMeters": [            {              "virtualMeterId": "string",              "sourceMeterIds": [                "string"              ]            }          ]        }      ]    }  ]}

meters.topology (version 1) POST

How a building's EOS meters (energy, water, waste) are connected: every meter with its carrier and whether it counts in the building total, the sub-meter tree (parent → child; a parent's consumption includes its children's, and the part no child measures is not sub-metered), what each virtual meter is calculated from with its factor, and overlappingBuildingMeters: virtual building meters fed by another building meter of the same building and carrier, or by its sub-meters, which EOS (like its dashboard) counts both, so the building total includes that consumption twice. Use it to explain a building's metering, to break a total down by sub-meter, and before trusting a building total.

consumption.meters (version 1) POST

Consumption of up to 10000 EOS meters (energy, water, waste; ids from meters.list) per Oslo-time bucket over [from, to), from the hourly values EOS processed (resets, gaps and virtual meter formulas handled): consumption, the estimated part, cost, missing hours and confidence per bucket, and per meter a total with the peak hour, coverage, cost coverage and hours per confidence tier. Values are consumption per hour, not meter readings: sum them, never take differences. Unit per meter: kWh, L or kg. null means no data, not zero (waste meters: no pickup is 0). For a building's total use consumption.buildings instead of adding meters: sub-meters are part of their parent. from and to must be whole hours; hour buckets up to 62 days, others up to 400, meters × days up to 20000.