Snapshot API

Query the current state of joins and windows via HTTP for initial UI hydration.

Snapshot API

The Snapshot API lets you query the current state of any join or window via a simple HTTP GET request. It solves the “cold start” problem: when a dashboard loads, it can fetch a snapshot of current results immediately instead of waiting for the next SSE event.

Endpoint

GET /snapshot

Available on any SSE sink’s HTTP server (the same address as /subscribe).

Query Parameters

Param	Required	Default	Description
join	yes	—	Join or window name, or * for all.
from	no	—	Start time (RFC 3339 or Unix seconds).
to	no	now	End time (RFC 3339 or Unix seconds).
limit	no	10000	Max rows per join/window.
keys	no	—	Comma-separated key filter.

Examples

Fetch all results

curl http://localhost:9100/snapshot?join=* | jq

Fetch a specific join

curl http://localhost:9100/snapshot?join=order-user-join | jq

Filter by keys

curl "http://localhost:9100/snapshot?join=order-user-join&keys=order_123,order_456" | jq

Time-range query

curl "http://localhost:9100/snapshot?join=order-user-join&from=2026-02-22T00:00:00Z" | jq

Response Format

The response is a JSON array of JoinResult objects — identical to SSE event payloads:

[
  {
    "query": "order-user-join",
    "key": "order_123",
    "rows": [
      {
        "order_id": "order_123",
        "amount": 45.00,
        "customer_name": "Alice"
      }
    ],
    "emit_at": "2026-02-22T10:00:00Z"
  }
]

Status Codes

Code	Meaning
200	Success (may be an empty array)
400	Invalid parameters
500	Query execution failed
503	Storage not ready (engine initializing)

Frontend Integration

Snapshot + SSE Pattern

The recommended pattern is to fetch a snapshot for initial state, then open an SSE stream for live updates:

async function connect() {
  const baseUrl = 'http://localhost:9100';

  // Hydrate current state
  try {
    const res = await fetch(`${baseUrl}/snapshot?join=*`);
    const results = await res.json();
    for (const result of results) {
      handleJoinResult(result);
    }
  } catch (e) {
    console.warn('Snapshot failed, will populate from SSE:', e);
  }

  // Then open SSE for live updates
  const es = new EventSource(`${baseUrl}/subscribe?join=*`);
  es.addEventListener('join_result', (event) => {
    handleJoinResult(JSON.parse(event.data));
  });
}

Replay Alternative

Instead of a separate fetch, add ?replay=true to the SSE URL:

const es = new EventSource('http://localhost:9100/subscribe?join=*&replay=true');

With replay, the server emits current results as SSE events (with "_replay": true) before switching to live streaming. The replay_complete event signals when initial hydration is done:

event: join_result
data: {"query":"...", "_replay": true, ...}

event: replay_complete
data: {"join":"*","count":42}

event: join_result
data: {"query":"...", ...}   ← live from here

Archive Queries

When the from parameter extends beyond the retention window (data has been compacted to Parquet), the snapshot handler automatically queries the archive federator if tiered storage is enabled.

This means a single /snapshot request can transparently query data across:

• Hot SQLite (recent data)
• Warm local Parquet files (days old)
• Cold cloud Parquet files (weeks/months old)

Configuration

The snapshot endpoint is enabled by default on any SSE sink. Optional tuning:

sinks:
  - name: dashboard
    type: sse
    config:
      addr: ":9100"
      snapshot:
        enabled: true
        default_limit: 10000
        timeout: 10s
        replay: true