Skip to content
Documentation Prelude Collector

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 capture endpoint polls the device on demand when the cache is stale; max-age=0 always polls before returning.
  • Capturing one exact model version. When several versions of a model coexist, address the capture by its immutable model-definition ID (/capture/{deviceId}/definition/{definitionId}) instead of by name. The ID pins one exact version and stays valid even if the model is later renamed.

Common pitfalls

  • Empty snapshots after creating a subscription. A subscription has to complete at least one cycle before its snapshot is populated. Until then the per-model endpoint returns 204 No Content. Wait one interval, or use the capture endpoint to poll now.
  • Treating snapshots as historical. Snapshots only hold the latest entries. For history, query the output backend you have configured (InfluxDB, Prometheus, etc.).
  • Calling capture on a tight loop. capture with max-age=0 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/subscription/snapshots/1

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

# 3. Force an on-demand collection during debugging (max-age=0 always polls).
curl -H "Authorization: Bearer <your-api-token>" \
  "https://collector.example.com/api/v1/capture/1/interface/latest?max-age=0"

# 4. Capture one exact version by its model-definition ID (survives renames).
curl -H "Authorization: Bearer <your-api-token>" \
  "https://collector.example.com/api/v1/capture/1/definition/7"

Bruno: 06 Snapshots / Get device snapshot, 06 Snapshots / Get model snapshot, 06 Snapshots / Capture snapshot (on-demand), 06 Snapshots / Capture by definition ID

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.

Model version. Capture responses carry model-name, model-version, and model-definition-id, so a response addressed by name still tells you which version was collected. The name-and-version route resolves the newest version when the version segment is latest (or empty); the definition-ID route targets exactly one version. The same model-version key identifies the version in output-backend payloads (NATS/Kafka/webhook/file), and reflects the version the subscription is pinned to (see the Subscriptions API).

Reference

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

See also

Filtering by: