Real-Time Stream API
Subscribe to a live stream of score updates, new events, and surge alerts as they happen. This endpoint uses Server-Sent Events (SSE) to push data to connected clients in real time.
GET /stream
Open a persistent SSE connection to receive real-time updates for the active Organizational Unit.
Request
No query parameters required. The connection remains open until the client disconnects.
Response
200 OK (Content-Type: text/event-stream)
The server sends JSON-encoded messages as SSE events. Each message includes a type field indicating the kind of update.
Message Types
| Type | Description |
|---|---|
score_update | A lead's score changed |
new_event | A new engagement event was ingested |
surge | A surge was detected for an account |
Message Fields
Score Update:
| Field | Type | Description |
|---|---|---|
type | string | score_update |
lead_id | string | Lead whose score changed |
score | integer | Updated score value |
New Event:
| Field | Type | Description |
|---|---|---|
type | string | new_event |
event | object | Full event object (see Events) |
Surge Alert:
| Field | Type | Description |
|---|---|---|
type | string | surge |
surge | object | Surge event details |
Example
curl -N "https://api.leadvibe.com/stream" \
-H "Authorization: Bearer <token>"
Example output:
data: {"type":"score_update","lead_id":"ld_abc123","score":85}
data: {"type":"new_event","event":{"event_id":"evt_001","lead_id":"ld_abc123","event_type":"page_view","timestamp":"2025-09-15T14:30:00Z"}}
data: {"type":"surge","surge":{"account_id":"acct_xyz","event_count":47}}
Common Errors
| Status | Meaning | Solution |
|---|---|---|
| 400 | Bad Request | Active OU must be set before connecting |
| 401 | Unauthorized | Check authentication credentials |
Notes
- The stream is OU-scoped -- you only receive updates for the active Organizational Unit
- The connection uses SSE (Server-Sent Events), which automatically reconnects if interrupted
- Keep-alive messages are sent periodically to maintain the connection
- For browser-based clients, use the native
EventSourceAPI or a library that supports SSE - Multiple clients can subscribe simultaneously; each receives the same updates