Readings API calls

from / to are epoch ms. Timezone is IANA (Europe/Warsaw), never browser. sourceValueType is the live valueType.name (num, int, bool, …) from parameter.get or a freeze snapshot.

Extent

{
  "workspaceId": "$workspaceId",
  "parameterIds": ["$parameterId"]
}

Extrema / one number

readings.minMax:

{
  "workspaceId": "$workspaceId",
  "parameters": [{ "parameterId": "$parameterId", "sourceValueType": "num" }],
  "from": 1710000000000,
  "to": 1710086400000
}

readings.aggregate (numeric aggregations: first / latest / average / delta / sum / min / max; int/string: first / latest):

{
  "workspaceId": "$workspaceId",
  "parameters": [
    {
      "parameterId": "$parameterId",
      "sourceValueType": "num",
      "aggregation": "max"
    }
  ],
  "from": 1710000000000,
  "to": 1710086400000
}

Each returned value carries its parameterId and aggregation, so one call can request several aggregations of the same parameter. Pairs without readings in the window are omitted.

Series

readings.cadence — closed buckets. Cadence: 1s 1m 5m 15m 30m 1h 4h 1d.

{
  "workspaceId": "$workspaceId",
  "parameters": [
    {
      "parameterId": "$parameterId",
      "sourceValueType": "num",
      "aggregation": "average"
    }
  ],
  "from": 1710000000000,
  "to": 1710086400000,
  "cadence": "1h",
  "timezone": "Europe/Warsaw"
}

readings.days — one row per local day (not cadence 1d):

{
  "workspaceId": "$workspaceId",
  "parameters": [
    {
      "parameterId": "$parameterId",
      "sourceValueType": "num",
      "aggregation": "average"
    }
  ],
  "from": 1710000000000,
  "to": 1710086400000,
  "timezone": "Europe/Warsaw"
}

readings.segments — N+1 chart slots:

{
  "workspaceId": "$workspaceId",
  "parameters": [{ "parameterId": "$parameterId", "sourceValueType": "num" }],
  "from": 1710000000000,
  "to": 1710086400000,
  "segmentCount": 200
}

readings.raw — same refs + window; optional maxPoints.

State history

readings.changePoints — when a state, mode, or fault code changed. It accepts only int and bool parameters. A parameter whose valueType.name is num fails with readings_unsupported_value_type, even when its values are whole numbers; read it with readings.raw or readings.exportExact instead, never by sending int.

{
  "workspaceId": "$workspaceId",
  "parameters": [{ "parameterId": "$stateParameterId", "sourceValueType": "int" }],
  "from": 1710000000000,
  "to": 1710086400000
}

Each series starts with the last stored reading at or before from, at its own timestamp, which may be earlier than from. Each later point is a value change in (from, to]; repeats of the same value are dropped. A series with one point means no change was stored through to. Without that first reading, the state before the first point is unknown. Gaps between stored readings can hide short changes.

Exact rows

readings.exportExact — one id, rows oldest first, up to limit (default and maximum 10,000) per page. While hasMore is true, the response carries next: send its afterTime and afterTimeSkip with the next request, unchanged. Several rows of one parameter can share a timestamp, for example readings imported from a device log with whole-second times, and next resumes inside such a timestamp without dropping or repeating rows. afterTime without afterTimeSkip skips every row at that time; it remains for older clients.

{
  "workspaceId": "$workspaceId",
  "parameterId": "$parameterId",
  "sourceValueType": "num",
  "from": 1710000000000,
  "to": 1710086400000
}

The next page repeats the request with the previous response’s next:

{
  "workspaceId": "$workspaceId",
  "parameterId": "$parameterId",
  "sourceValueType": "num",
  "from": 1710000000000,
  "to": 1710086400000,
  "afterTime": 1710043200000,
  "afterTimeSkip": 2
}

Occupied ranges (any member)

readings.rangeOccupied checks which parameters already have readings in the requested ranges. It requires workspace membership, including view_only, and does not change readings.

{
  "workspaceId": "$workspaceId",
  "sourceValueType": "num",
  "ranges": [{ "parameterId": "$parameterId", "from": 1710000000000, "to": 1710086400000 }]
}

Writes (editors and above; clearing needs an admin)

readings.insertExact:

{
  "workspaceId": "$workspaceId",
  "sourceValueType": "num",
  "points": [
    {
      "parameterId": "$parameterId",
      "family": "num",
      "time": 1710000000000,
      "rawHex": "0000",
      "value": 21.5
    }
  ]
}

family must be the reading family of that sourceValueType (num / int / str / bigint / datetime / geo).

readings.clearRange and readings.rebuildParentRollups take ranges:

{
  "workspaceId": "$workspaceId",
  "sourceValueType": "num",
  "ranges": [{ "parameterId": "$parameterId", "from": 1710000000000, "to": 1710086400000 }]
}

clearRange needs the admin or owner role and is recorded in activity history with the spans it cleared. It recalculates affected aggregates by default; rebuildRollups: false skips recalculation. To delete whole parameters, periods, or everything before a date, with a count first, use storage.readingsDeletePreview and storage.deleteReadings (manage stored data).

Readings recorded on an MC252

These procedures cover the readings that MC252 programs record on the device (recorded readings). Each takes { "endpointId": "$endpointId" } except deviceLog.backfill.

• deviceLog.status returns the import period (pullMinutes), the end of the last complete import (lastImportAt), and the time through which every recorded reading is in history (completeThrough). While the device clock is more than five minutes off, clock holds its offset and since when; otherwise it is null.
• deviceLog.listAddresses lists the recorded addresses that no parameter reads, as the Recorded readings tab shows them, with each address’s latest type code (typeCode).
• deviceLog.backfill takes { "parameterId": "$parameterId" }, a Modbus parameter on the same endpoint with the address’s unit ID, table, and first address, and copies the stored records into its history. It skips readings the parameter already has, so a repeated call adds nothing. It returns the id of the job, or null when another user’s backfill of the parameter is running. Editors, admins, and owners can call it.

parameter.get and parameter.listTree return a deviceLog object ({ pullMinutes, lastImportAt, completeThrough }) for a parameter that receives recorded readings, and null otherwise.