Session Lifecycle

A session is one streaming connection's worth of data. Understanding its lifecycle helps you reason about what your client app sees, what gets stored, and what you can query later.

When a session opens

A session is created the moment a device successfully connects to /stream/ingest and the server completes the handshake. The handshake's session_id is your handle for this session.

No separate "start session" API call. No explicit registration. Connect → session.

During the session

As frames arrive, the pipeline:

1. Buffers raw samples in per-session streams.
2. At each node's tick interval, reads a window of samples, runs the algorithm, and emits either a feature (intermediate) or an insight (final output).
3. Publishes insights on /stream/subscribe and persists them to the database.

Everything (frames, features, insights) is tagged with the session_id.

When a session ends

A session ends when any of:

• The client closes the WebSocket.
• The server closes the WebSocket (e.g. auth revoked mid-session, idle timeout).
• The network drops and the TCP connection times out.

The server marks the session closed in the database and stops its pipeline tasks. Any in-flight insight computations already scheduled will complete and publish, but no new ones start.

Reconnecting creates a new session. There's no resume.

Querying past sessions

Once a session ends, its metadata and all computed insights are stored and queryable via REST.

List your account's recent sessions:

GET /v1/sessions
Authorization: Bearer raeh_...

Response:

[
  {
    "id": "ad225407-36de-48b1-bcf2-14d5c057aeca",
    "device_id": "xyz-watch-a3b5",
    "device_model_id": "573fdc48-...",
    "status": "closed",
    "started_at": "2026-04-14T16:41:05.000Z",
    "ended_at":   "2026-04-14T16:43:35.000Z"
  }
]

Get all insights for one session:

GET /v1/sessions/{session_id}/insights
Authorization: Bearer raeh_...

Response is an array of insight objects, same shape as what you receive live on /stream/subscribe, plus a few diagnostic fields (window coverage, end-to-end latency) useful for post-hoc analysis.

See Reference → REST API for the full schema.

What's retained

• Session rows (device, start/end time, status): indefinitely.
• Insights (HR, SpO₂, RR values): indefinitely.
• Raw frames: buffered in Valkey during the session, not retained after it ends.
• Intermediate features: same as raw frames, buffered only during the session.

If you need raw-sample retention for later reprocessing, let us know. It's not part of the default product.

Typical durations

A session is however long the connection lasts. In practice:

• Continuous-wear wearables (wristband, patch): 8–24 hour sessions, sometimes multi-day.
• Workout apps: 30-minute to 2-hour sessions.
• Spot-check tools: 30–60 second sessions.

The pipeline doesn't care; it ticks every ~2 seconds for HR regardless of how long the session runs.

Can I run multiple sessions at once?

Yes. Many devices (or many instances of the same device reconnecting fast) can stream concurrently under the same account. Insights from each are tagged with their own session_id and device_id so your client app can route them correctly.