Read history

Nodelets saves readings of every observable property of a connected Nodelet, whether or not anyone is watching. There is nothing to switch on. A property is collected when its definition has an observeproperty binding and it is not marked writeOnly. MQTT properties cannot be observed, so they have no history.

Reading history needs Read history. A key with it on one property reads that property alone; see Create an API key with permissions.

What is saved

Each account’s plan gives every Nodelet a budget of saved readings per day, shared evenly across its observable properties. The budget becomes a steady gap between saved readings, reported as sampling.everySeconds. A property that reports more often than the gap has one reading saved per gap, and that reading’s sampleInterval says how many readings it stands for, itself included. A property that reports less often has every reading saved.

Plan budgets are placeholders while Nodelets is pre-release.

Each saved reading carries the time the cloud received it, not the device’s time, and a sequence number. Sequence numbers run across all of one Nodelet’s properties.

Read recent readings

curl -fsS -H "Authorization: Bearer $NODELETS_KEY" \
  "https://api.staging.nodelets.com/nodelets/$NODELET/observations/recent?property=temperature&limit=3"

{
  "observations": [
    {"property": "temperature", "value": 21.43, "receivedAt": 1794060130131, "sequence": 814, "sampleInterval": 12, "definitionRevision": 1},
    {"property": "temperature", "value": 21.41, "receivedAt": 1794060070102, "sequence": 813, "sampleInterval": 12, "definitionRevision": 1},
    {"property": "temperature", "value": 21.40, "receivedAt": 1794060010095, "sequence": 812, "sampleInterval": 12, "definitionRevision": 1}
  ],
  "sampling": {"type": "time", "everySeconds": 60},
  "uncertain": [],
  "uncertainFrom": null,
  "movedThrough": null,
  "evictedThrough": null,
  "nextCursor": "YmVmb3JlOjgxMg=="
}

Readings come newest first. limit is 1 to 1,000 and defaults to 100. Leave out property to read every property, which needs Read history on all of the Nodelet’s capabilities.

Page through older readings

Pass nextCursor back as cursor:

curl -fsS -H "Authorization: Bearer $NODELETS_KEY" \
  "https://api.staging.nodelets.com/nodelets/$NODELET/observations/recent?property=temperature&cursor=YmVmb3JlOjgxMg=="

When nextCursor is null, recent storage holds nothing older. If movedThrough is set, older readings have moved to the archive. Read them from observations/archive with the same parameters:

curl -fsS -H "Authorization: Bearer $NODELETS_KEY" \
  "https://api.staging.nodelets.com/nodelets/$NODELET/observations/archive?property=temperature"

The archive is slower. A page can come back with fewer readings than limit and still have a nextCursor; carry on until it is null. evictedThrough says where the archive now starts: readings at or below that sequence have gone to keep within the plan’s storage.

Check what history can vouch for

uncertain lists the intervals on the page that history cannot vouch for, each with a property (or null for all of them), a reason, a count where known, and firstAt and lastAt. Reasons include BRIDGE_DISCONNECTED and BRIDGE_QUEUE_FULL. A reading skipped by sampling is never an uncertain interval. uncertainFrom is set when older intervals have gone, so an older page cannot vouch for itself.

To see whether collection is running for each Nodelet:

curl -fsS -H "Authorization: Bearer $NODELETS_KEY" \
  https://api.staging.nodelets.com/observations/health

Each Nodelet’s status is complete when every property is collected, degraded when some are not, and unavailable when its bridge could not answer. Each property lists its state and, when it is not collected, a code.

Follow new readings

The account feed sends each saved reading as it is saved, for every Nodelet the key may read the history of. It authenticates with the key in a header and uses the nodelets.feed.v1 subprotocol. With websocat:

websocat --protocol nodelets.feed.v1 \
  -H "Authorization: Bearer $NODELETS_KEY" \
  wss://api.staging.nodelets.com/observations/stream

{"jsonrpc":"2.0","method":"observation","params":{"nodeletId":"nl_5c0e8a2f-7d41-4b9e-a3c6-2f8d1e4b7a90","name":"temperature","value":21.44,"receivedAt":1794060190140,"sequence":815,"sampleInterval":12}}

The feed replays nothing and a delivery can be missed. A skip in one Nodelet’s sequence shows that something was missed; fetch it with a recent query. Send nothing on the feed: a message from the client closes it.

From an AI client

The read_history MCP tool reads the same two queries. See MCP tools.

Limits

• History holds what sampling kept. A short spike between saved readings can be missing, and so can the last change in a burst until the next reading arrives.
• Spacing is firm for properties that report often. For a property that reports less often than about every 10 seconds, readings can be saved more often than the gap.
• A bridge collects at most 64 properties. Past that, the health report names the properties that are not collected.
• A key limited to some properties can see from gaps in sequence how many readings the other properties saved, though not their values.
• Removing a device deletes its readings. Reads stop at once, and the stored readings are deleted shortly after.
• No dashboard page shows history yet.