Skip to content
Documentation Prelude Collector 1.0.0

Snapshots API

Read the latest cached telemetry from active collection sessions in Prelude Collector — when to use snapshots, common pitfalls, and a worked example.

A snapshot is the most recent parsed-data view that the Prelude Collector holds for a given device and model. After this first mention, the rest of this page refers to Prelude Collector as "the collector". Snapshots are read-only and live in memory: they let you inspect what the collector has gathered without waiting for the next output cycle and without touching downstream storage. This page covers when to call the API, common mistakes, and a worked example. For the full endpoint schema, see the API reference.

When to use this API

  • Verifying that a new subscription is producing data. Hit the per-model snapshot right after starting a subscription instead of waiting for the next output flush.
  • Building lightweight in-app inspectors. Snapshots are cheap to read; they are well suited to UIs that need to render "what does this device look like right now" without querying a TSDB.
  • Forcing a re-collection during debugging. The per-model endpoint accepts ?refresh=true, which triggers an on-demand collection before returning.

Common pitfalls

  • Empty snapshots after creating a subscription. A subscription has to complete at least one cycle before its snapshot is populated. Wait one interval, or use ?refresh=true.
  • Treating snapshots as historical. Snapshots only hold the latest entries. For history, query the output backend you have configured (InfluxDB, Prometheus, etc.).
  • Calling refresh on a tight loop. refresh=true triggers a real device call. Don't drive it from polling dashboards — use it for ad-hoc debugging only.
  • Mismatched model name. The path uses the model name, not the ID. A typo returns 404 Not Found.

Worked example: confirm fresh data on a new subscription

# 1. Read everything the collector currently has for device 1.
curl -H "Authorization: Bearer <your-api-token>" \
  https://collector.example.com/api/v1/snapshots/1

# 2. Drill into a specific model.
curl -H "Authorization: Bearer <your-api-token>" \
  https://collector.example.com/api/v1/snapshots/1/interface

# 3. Force a refresh during debugging.
curl -H "Authorization: Bearer <your-api-token>" \
  "https://collector.example.com/api/v1/snapshots/1/interface?refresh=true"

Bruno: 06 Snapshots / Get device snapshot, 06 Snapshots / Get model snapshot, 06 Snapshots / Refresh snapshot

The response entries array contains parsed rows that match the model schema; raw-updates exposes the protocol-level payload the collector decoded from. If entries is empty but raw-updates is not, the issue is almost always a mapping problem — go fix it via the Models API and try again.

Reference

Exact response shapes for both endpoints are in the Bruno collection.

See also

Filtering by: