Realtime model events

Connect

curl --no-buffer \
  -H "Authorization: Bearer $GRID_TOKEN" \
  "$GRID_URL/api/models/revenue-api/events"

The response uses text/event-stream.

Initial synchronization

Ordinary payloads arrive as default SSE message events:

data: {"type":"stream:hello","streamId":"stream-..."}

data: {"type":"model:snapshot","snapshot":{...}}

data: {"type":"symbol:update","snapshot":{"symbol":"Revenue","status":"ready","value":{"kind":"number","value":120000,"typeTag":"number"},"requestRev":1,"resolvedRev":1}}

The initial model:snapshot is a manifest/control-plane snapshot. It does not contain every evaluated workbook value. After adopting it, resolve visible symbols or fetch visible ranges.

Use ?snapshot=false only when the client has another explicit synchronization path.

Frames and heartbeats

Supported top-level message types include:

• stream:hello
• model:snapshot
• symbol:update
• range:update
• presence:state
• comment:update

The server also sends a named heartbeat every five seconds:

event: heartbeat
data: {}

Reconnect and resynchronize

The stream does not emit SSE id fields and does not implement Last-Event-ID replay. A reconnect is not a gap-free resume.

After a missed-heartbeat threshold or network failure:

1. Close the silent connection.
2. Reconnect with bounded exponential backoff and jitter.
3. Leave the default initial snapshot enabled.
4. Refetch currently visible symbols or ranges.
5. Re-send viewport and presence state.

Browser authentication

Browser EventSource cannot add an Authorization header. Prefer same-origin session authentication or a scoped server-side proxy. Query-token fallback may be supported by a deployment, but URL tokens can leak through logs and history; treat it as an explicit operator-approved tradeoff rather than the default recipe.