Use casesPartners and pipelinesLive dashboards06 / 12
How it fits together

Every run, and every new result, to whoever may see it

A call through any front door is recorded as it completes: one history row and one event, in the same batch. A separate events server reads every instance's events from the shared store and streams each one, over plain HTTP, only to the keys allowed to see it. With live queries (experimental), a change to the data makes the same server run each subscribed query again as its viewer, and send the result only if it changed.

9,000streams in one process, measured
0.75 sfor an event to reach all of them
24 ha client can resume from
Runs happen
The governed core
Shared store
Events server
Who watches
↗

Partner backend

GET /q/orders_by_customer
source: rest
↗

AI agent

tools/call orders_summary
source: mcp
↗

Nightly export

nightly_orders → s3://
source: export
The governed core↗
× each instance 01020308
Identity · who is asking
Policy · what they may see
Execution · run, mask, format
08 · Record it
One history row and one event, in the same batch

The same core as on Home: these runs were governed first.

↗

Event log

shared store

One event per run, kept 24 h by default, whatever run history keeps.

PostgreSQLNOTIFY · wakes it at once SQLitepolled every 1 s ClickHouse run storepolled · 1 s settleExp↗
↗ queryapigate events Stable own port · /events behind your proxy
key checked, and again every 60 s✓ a key sees its own runs; admin sees all✓ filters narrow, never widen✓ resume with Last-Event-ID✓
↗

Ops screen

admin · every run
export nightly_orders 2,310 rows 1.4 srest orders_by_customer 38 rows 12 ms
↗

Partner portal

key partner-acme · its own runs
rest orders_by_customer 41 rows 14 msrest orders_by_customer 38 rows 12 ms
↗

Failures board

admin · ?status=error
mcp orders_summary error timeoutrest orders_by_customer error timeout
↗

Debezium Server

reads the change logPOST /ingest/cdc/<source>
signed · Standard Webhooks

A signal

table names, never rowsQueryAPIGate's own writes
signal the same way

table.changed

in the event logexamples · rental

Re-run as the viewer

Expgrants · filters · maskingsent only if it changed
at most once a second
↗

Regional dashboard

GET /live/orders_by_region · north
result north · 413 open changeresult north · 412 open subscribe
What arrivesone frame per run: the record, never a row's values
id: 4182 source rest query orders_by_customer v1 status success rows 38 12 ms key partner-acme
Stablecompatibility promise Expmay change in a minor release Or GET /events on the main server: no extra process, up to 4 streams, its own process only, no resume.
Runs happenApps, partners, AI agents and exportsEvery run through a front door is recorded, with source set to rest, mcp or export.
The governed coreIdentity → policy → execution → recordEach run is recorded as it completes: one history row and one event, in the same batch, on every instance.
Shared storeThe event logKept 24 h by default. PostgreSQL wakes the events server at once; SQLite and the ClickHouse run store (experimental) are polled every second.
Events server Stablequeryapigate eventsThousands of streams per process. A key sees its own runs, the admin key sees all, and filters only narrow.
Who watchesOps screens, partner portals, failure boardsEach gets frames with who, which query, status, rows and timing, never a row's values.
Live queries ExpA change, then the result againA write through QueryAPIGate, or a change Debezium Server reads from the database's log, signals the tables that changed - never rows.
Events serverRe-run as each viewerEach subscribed query that reads those tables runs again with the viewer's grants, row filter and masking, at most once a second, and is sent only if its result changed.
Who watchesA regional dashboard on GET /live/Its own region's result, and nobody else's rows.

The same governed core as the full architecture.

For screens that stay current

A screen that updates when the data changes, each viewer seeing only their rows

A dashboard, an order screen or a stock level should change when the data does - not when the next poll comes round. Subscribe to the saved query the screen already calls. QueryAPIGate sends its current result, then the new one each time the tables behind it change, whether the change came through QueryAPIGate or straight into the database through Debezium. Each result is run as the viewer: a regional manager's screen shows their region, and nobody else's rows ever reach it.

The shape of the call
GET /live/example_kpi_active_rentals → event: result with reason: subscribe, then reason: change after each changeGET /events?query=... → who ran what, as it happens
What you stop building
✓A polling loop.
✓A websocket service.
✓A cache you have to invalidate by hand: the same signals expire cached GET /q/ answers that read the changed tables.
✓A second permission check on the push path: a key that may not run the query gets the same 403 as GET /q/, before any stream opens.

ExperimentalLive queries are new in 0.51 and off unless QUERYAPIGATE_LIVE_QUERIES=1; their route, events and settings may change in a minor release. Run events are stable.

The other half: who ran what
✓Server-sent events over plain HTTP: a fetch stream in the browser with the key in a header, no WebSocket infrastructure.
✓Per-key feeds, so a partner can watch their own calls and nobody else's.
✓Across several instances, queryapigate events reads every instance's runs from the shared store, woken by a PostgreSQL notification.
✓Stable since 0.34, under the compatibility promise. Filter by query, connection, kind or status.
Live dashboards
# subscribe: the current result now, the new one after each change
curl -N 'https://data.example.com/live/example_kpi_active_rentals' \
  -H 'X-API-Key: <the dashboard key>'

event: result
data: {"query": "example_kpi_active_rentals", "params": {},
       "rows": [{"active_rentals": 798}], "truncated": false,
       "reason": "subscribe", "refreshed_at": "2026-11-17 10:03:53"}

# an UPDATE to rental, through QueryAPIGate or Debezium
event: result
data: {"query": "example_kpi_active_rentals", "params": {},
       "rows": [{"active_rentals": 799}], "truncated": false,
       "reason": "change", "refreshed_at": "2026-11-17 10:03:56"}

# the other half: who ran what, one frame per run
curl -N 'https://data.example.com/events?query=orders_by_customer' \
  -H 'X-API-Key: <the ops key>'

id: 4182
data: {"type": "query.run", "source": "rest", "kind": "saved",
       "query": "orders_by_customer", "version": 1, "connection_name": "shop",
       "entry": {"status": "success", "rows": 38, "duration_ms": 12,
                 "key_name": "partner-acme", ...}}
More use casesAll twelve →

Not sure which fits?

The example APIs ship with a generated database and one scoped key per scenario, so you can try each of these in a few minutes without connecting anything of your own.

Run the examplesCompare alternatives