Streaming Queries (SSE)
Subscribe to a live stream of records matching a filter using Server-Sent Events.
What you'll learn
- ✓GET /v1/agents/:id/query/stream?field=&op=&value=&limit=
- ✓Each matching record streamed as an SSE event
- ✓Stream closes after limit events or client disconnect
- ✓JavaScript EventSource API for browser consumption
- ✓Real-time dashboard pattern — no polling
Open SSE stream in one terminal. Write 5 records in another. Confirm they appear in the stream in real time.
Interactive Walkthrough
What you'll learn
Subscribe to a live stream of records matching a filter using Server-Sent Events.
Open an SSE stream
curl -N "http://localhost:7475/v1/agents/events/query/stream?field=type&op=eq&value=payment&limit=100" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY"Each matching record is streamed as an SSE event:
`
data: {"content_hash":"b3a7c2...","payload":{"type":"payment","amount":99.00}}
data: {"content_hash":"d4e5f6...","payload":{"type":"payment","amount":149.00}}
`
The stream closes after limit events are sent (or you close the connection).
Stream in JavaScript
`javascript
const evtSource = new EventSource(
'http://localhost:7475/v1/agents/events/query/stream?field=type&op=eq&value=payment&limit=100',
{ headers: { Authorization: Bearer ${ROOT_KEY} } }
);
evtSource.onmessage = (e) => {
const record = JSON.parse(e.data);
console.log('New payment:', record.payload.amount);
};
`
Real-time dashboard pattern
Use SSE to power live dashboards:
1. Open SSE stream on events agent filtered to type = "checkout"
2. Each event updates a running total on the frontend
3. No polling required — the server pushes each record as it is written
Challenge
Open an SSE stream in one terminal. In another terminal, write 5 records to the same agent. Observe them appear in the SSE terminal in real time.
---