History

Server

Read and correct a point's stored history. Exists primarily so Baler can act as a drop-in history-storage backend for Haxall/SkySpark's IHisExt extension point (span-based read, point-scoped read/write/delete) - see the "Haxall drop-in" doc page.

Read a point's stored history over a time span

GET

http://localhost:8080/ingest

/history

Mirrors Haxall's IHisExt.read span semantics: start/end are both optional and inclusive - omit both for the point's entire history. Results are always ordered oldest-first.

Read a point's stored history over a time span › query Parameters

point

string · required

Same raw topic/label POST /ingest uses - resolved to the same point identity internally.

start

number

Unix epoch seconds, inclusive. Omit for the beginning of history.

end

number

Unix epoch seconds, inclusive. Omit for the current time.

Read a point's stored history over a time span › Responses

Matching history items, oldest first. Empty array if the point has no history in range.

HistoryItem[]

HistoryItem

ts

number · required

Unix epoch seconds.

required

Whatever type was originally stored.

quality

string · enum

Present only on a flagged sample (#183). The value is kept as received; fault rules and Cx checks skip flagged samples.

Enum values:

fault

overridden

out_of_service

out_of_range

spike

unit_suspect

Delete one point's history item at an exact timestamp

DELETE

http://localhost:8080/ingest

/history

The Baler side of Haxall's IHisExt.write delete convention (a written value equal to xeto::None.val means "remove this item", not "store null"). Deletes at most one row - the one at exactly this timestamp.

Delete one point's history item at an exact timestamp › query Parameters

point

string · required

ts

number · required

Unix epoch seconds, exact match.

Delete one point's history item at an exact timestamp › Responses

Deleted. No response body.

No data returned

Axon-style `readAll(filter).hisRead(span)` - many points' history in one call

GET

http://localhost:8080/ingest

/his

The SkySpark "what is this AHU doing?" query, against Baler's own graph + history: a Haystack filter picks entities, hisRead picks the span, an optional hisRollup folds the raw samples into fixed buckets. Points that match are read directly; equipment that matches is expanded to every point it brick:hasPoint (the one deliberate departure from Axon, where hisRead on an equip is an error) - so read(ahu).hisRead(today) is enough to see a whole air handler. Rendered as charts by the demo UI at /ui/his.html.

Grammar (see hisquery.py for the full set of error messages):

Code
readAll(<filter>).hisRead(<span>)[.hisRollup(<fold>, <interval>)]
read(<filter>)...          # first match only; 404 if nothing matches
<filter>                   # bare filter = readAll(...).hisRead(today)

filter: Haystack filter syntax - ahu, air and temp and sensor, not vav, equipRef == @AHU-1, id == @urn:equip:fbf/ahu-1, kind == "Bool", temp > 72, parentheses. A name matches three ways at once, so Brick-typed data needs no Brick spelling: as a Haystack marker (haystack:hasTag); as a Brick class - case-insensitive, with every subclass and Brick alias folded in (Temperature_Sensor finds Zone_Air_Temperature_Sensor points; AHU, Air_Handling_Unit, air_handling_unit all find air handlers and rooftop units); and as a Brick tag word, the words a class name is made of (temperature and sensor, zone and air and temp and sensor - Haystack spellings temp, sp, cmd, equip are mapped). Hierarchy comes from the vendored ontology/Brick-only.ttl, so this works whether or not Brick is loaded into the graph. point/equip/site also match on graph structure, since BACnet-sourced entities never got those as explicit tags. Not supported: -> tag paths, arithmetic, unit conversion.
span: today, yesterday, thisWeek, lastWeek, pastWeek, thisMonth, lastMonth, pastMonth, thisQuarter, lastQuarter, thisYear, lastYear, pastYear (with or without ()), a date 2026-09-03, a month 2026-09, a year 2026, or a range 2026-09-01..2026-09-07. Resolved in tz; weeks start Monday.
rollup: fold is one of avg, min, max, sum, count; interval is <n><unit> with unit sec, min, hr, day, wk, mo (1/3 only), yr. Booleans fold as 0/1; each bucket is stamped with its start.

Axon-style `readAll(filter).hisRead(span)` - many points' history in one call › query Parameters

expr

string · required

The query, as written above.

tz

string

IANA zone the span is resolved in. Defaults to BALER_TZ, else UTC.

limit

integer · min: 1 · max: 200000

Max raw samples per point (ignored for rollups). Defaults to 10000, same as SkySpark's hisRead default; each series reports truncated: true if it hit this.

compact

string · enum

1: each series' history is two parallel arrays, {"ts": [...], "value": [...]}, instead of one {ts, value} object per sample - the same data in about half the bytes (Baler#107). Whole-second timestamps are integers. Omit for the default form.

Enum values:

true

Axon-style `readAll(filter).hisRead(span)` - many points' history in one call › Responses

One series per resolved point, each with its metadata and history for the span.

HisQueryResult

expr

string · required

The expression as received.

mode

string · enum · required

Enum values:

read

readAll

filter

string · required

Just the filter part of the expression.

object · required

required

Present when the expression had a hisRollup; every series is then numeric and bucket-stamped.

limit

integer · required

The per-point raw-sample cap that applied.

matched

string[] · required

URIs the filter matched (before equipment-to-point expansion), first 200.

matchedCount

integer · required

object[] · required

Only ever non-empty when matchedCount is 0: filter names that are almost a Brick class or tag word (Air_Handeling_Unit, temperture), with the nearest real ones. Never an error - the name may be a valid Haystack marker or PROJ class the vendored Brick can't know about.

HisSeries[] · required

GET/his

curl 'http://localhost:8080/ingest/his?expr=readAll(ahu).hisRead(today)'

Example Responses

{
  "expr": "expr",
  "mode": "read",
  "filter": "filter",
  "span": {
    "start": 0,
    "end": 0,
    "label": "label",
    "tz": "tz"
  },
  "rollup": {
    "fold": "avg",
    "interval": "1hr"
  },
  "limit": 0,
  "matched": [
    "string"
  ],
  "matchedCount": 0,
  "hints": [
    {
      "token": "token",
      "suggestions": [
        "string"
      ]
    }
  ],
  "series": [
    {
      "id": "id",
      "point": "point",
      "dis": "dis",
      "unit": "unit",
      "kind": "kind",
      "brickClass": "brickClass",
      "tags": [
        "string"
      ],
      "equip": "equip",
      "equipDis": "equipDis",
      "history": [
        {
          "ts": 0,
          "value": 0,
          "quality": "fault"
        }
      ],
      "truncated": true
    }
  ]
}

json

application/json

Ingest Other endpoints

Read a point's stored history over a time span

GET

http://localhost:8080/ingest

/history

Mirrors Haxall's IHisExt.read span semantics: start/end are both optional and inclusive - omit both for the point's entire history. Results are always ordered oldest-first.

Read a point's stored history over a time span › query Parameters

point

string · required

Same raw topic/label POST /ingest uses - resolved to the same point identity internally.

start

number

Unix epoch seconds, inclusive. Omit for the beginning of history.

end

number

Unix epoch seconds, inclusive. Omit for the current time.

Read a point's stored history over a time span › Responses

Matching history items, oldest first. Empty array if the point has no history in range.

HistoryItem[]

HistoryItem

ts

number · required

Unix epoch seconds.

required

Whatever type was originally stored.

quality

string · enum

Present only on a flagged sample (#183). The value is kept as received; fault rules and Cx checks skip flagged samples.

Enum values:

fault

overridden

out_of_service

out_of_range

spike

unit_suspect

Delete one point's history item at an exact timestamp

DELETE

http://localhost:8080/ingest

/history

Delete one point's history item at an exact timestamp › query Parameters

point

string · required

ts

number · required

Unix epoch seconds, exact match.

Delete one point's history item at an exact timestamp › Responses

Deleted. No response body.

No data returned

Axon-style `readAll(filter).hisRead(span)` - many points' history in one call

GET

http://localhost:8080/ingest

/his

Grammar (see hisquery.py for the full set of error messages):

Code
readAll(<filter>).hisRead(<span>)[.hisRollup(<fold>, <interval>)]
read(<filter>)...          # first match only; 404 if nothing matches
<filter>                   # bare filter = readAll(...).hisRead(today)

filter: Haystack filter syntax - ahu, air and temp and sensor, not vav, equipRef == @AHU-1, id == @urn:equip:fbf/ahu-1, kind == "Bool", temp > 72, parentheses. A name matches three ways at once, so Brick-typed data needs no Brick spelling: as a Haystack marker (haystack:hasTag); as a Brick class - case-insensitive, with every subclass and Brick alias folded in (Temperature_Sensor finds Zone_Air_Temperature_Sensor points; AHU, Air_Handling_Unit, air_handling_unit all find air handlers and rooftop units); and as a Brick tag word, the words a class name is made of (temperature and sensor, zone and air and temp and sensor - Haystack spellings temp, sp, cmd, equip are mapped). Hierarchy comes from the vendored ontology/Brick-only.ttl, so this works whether or not Brick is loaded into the graph. point/equip/site also match on graph structure, since BACnet-sourced entities never got those as explicit tags. Not supported: -> tag paths, arithmetic, unit conversion.
span: today, yesterday, thisWeek, lastWeek, pastWeek, thisMonth, lastMonth, pastMonth, thisQuarter, lastQuarter, thisYear, lastYear, pastYear (with or without ()), a date 2026-09-03, a month 2026-09, a year 2026, or a range 2026-09-01..2026-09-07. Resolved in tz; weeks start Monday.
rollup: fold is one of avg, min, max, sum, count; interval is <n><unit> with unit sec, min, hr, day, wk, mo (1/3 only), yr. Booleans fold as 0/1; each bucket is stamped with its start.

Axon-style `readAll(filter).hisRead(span)` - many points' history in one call › query Parameters

expr

string · required

The query, as written above.

tz

string

IANA zone the span is resolved in. Defaults to BALER_TZ, else UTC.

limit

integer · min: 1 · max: 200000

Max raw samples per point (ignored for rollups). Defaults to 10000, same as SkySpark's hisRead default; each series reports truncated: true if it hit this.

compact

string · enum

Enum values:

true

Axon-style `readAll(filter).hisRead(span)` - many points' history in one call › Responses

One series per resolved point, each with its metadata and history for the span.

HisQueryResult

expr

string · required

The expression as received.

mode

string · enum · required

Enum values:

read

readAll

filter

string · required

Just the filter part of the expression.

object · required

required

Present when the expression had a hisRollup; every series is then numeric and bucket-stamped.

limit

integer · required

The per-point raw-sample cap that applied.

matched

string[] · required

URIs the filter matched (before equipment-to-point expansion), first 200.

matchedCount

integer · required

object[] · required

HisSeries[] · required