/realtime/subscribeSubscribe to Realtime Feed
Upgrades the connection to a WebSocket or SSE stream to receive live events for a named topic.
The topic query parameter must match one of the six platform topics:
collections.<name>.*studio.workflows.runs.*studio.queries.executed.*studio.dashboards.refresh.*forge.functions.invocations.*audit.org.*
It may also be the project's live audit tail, audit.project.* (or audit.project.<type>).
Row-level security is evaluated per event at delivery time, so subscribers receive only events for rows they are authorised to read.
On a collections.<name>.* topic an optional filter narrows delivery further, with the same operators and meaning as a collection read's filter: a bare value means eq (null matches a NULL column), and an operator object ANDs its operators, such as:
{"amount":{"gte":1000,"lt":5000},"status":{"in":["paid","shipped"]}}not negates the operators inside it, as on a read ({"status":{"not":{"eq":"cancelled"}}}); or, joins and aggregates are not supported.
It never widens what row-level security allows.
A filter may name only columns you can read as plaintext through the data API.
Deletes can't be checked against a filter, so a filtered subscription receives row_deleted for every row it can read on the topic, including rows that never matched.
Errors:
K9O_INVALID_FILTER(400), before the stream opens, for a malformed or refused filter or an unrecognised topicK9O_SUBSCRIPTION_LIMIT_EXCEEDED(429) when the project's concurrent-subscription cap is reached
Each event frame's SSE id is the event's eventId, the same on every gateway replica.
The server closes a connection after a while; reconnect with Last-Event-ID set to the last eventId you received to resume.
The resumed stream can repeat a few events you already have, so drop duplicates by eventId.
If the stream can't be resumed, it sends event: resync: re-read current state through the data API, then carry on.
The audit tail (audit.project.*) needs the same access as the audit log (PROJECT_AUDITOR, PROJECT_ADMIN, or an org admin or owner; K9O_RBAC_DENY (403) otherwise), re-checked while the stream is open.
Each frame carries only auditEventId, type, actorType, occurredAt and outcome: read the full event from the audit log.
It covers every project audit event except warden.checkpoint (gate-frame evidence checkpoints), which the live tail excludes: read those from the audit log or the replay.
When an audit-tail stream can't be resumed, its event: resync says replay-ledger: catch up through the replay endpoint, then reconnect.
| projectSlug * | path | The project's slug, as in |
| topic | query | Required. The topic to listen on: an exact topic or a prefix ending in A missing or unknown topic answers 400 |
| filter | query | A JSON object of conditions on the collection's columns, all of which must hold, with the same operators and meaning as a collection read's filter. A bare value means An operator object ANDs its operators, for example: Operators: Operands:
As on a read, a NULL column never matches a negated comparison (use Not supported: Valid only on a At most 16 columns and 32 conditions. Each column must be one you can read as plaintext through the data API, under every operator: an unknown, encrypted, field-protected or masked column, or one your column grants don't let you read, is refused. A refusal is 400
A A pattern, path, range or array literal Postgres can't read is Each delivered batch is checked in one query with a time limit (2000 ms by default). When the check can't pass, the stream sends
Re-read current state, then subscribe again: with a filter that holds after The filter applies to every row event but |
| fromSequence | query | The resume cursor, an Omitted, the stream starts with the recent events the server holds. |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | A Server-Sent Events stream of the project's live events on `topic`. | |
| 400 | K9O_INVALID_FILTER | The topic is unknown, or the filter is malformed or refused: not a JSON object of column conditions, an unsupported operator, on a topic other than one collection's, or naming a column you can't read as plaintext. `context.key` names the column and `context.reason` the cause. |
| 401 | K9O_SESSION_EXPIRED | Your session has expired; sign in again to establish a new subscription. |
| 401 | K9O_INVALID_CREDENTIALS | The credentials provided are not valid; the subscription could not be opened. |
| 403 | K9O_ACCESS_DENIED | Your role does not permit subscribing to this resource. |
| 403 | K9O_RBAC_DENY | The audit topics (audit.project.*) need GET /audit-log's authority: PROJECT_AUDITOR or PROJECT_ADMIN (or an org admin or owner). |
| 403 | K9O_IAM_POLICY_DENIED | The bound IAMPolicy ceiling denies audit_log:query, which the audit topics (audit.project.*) require. |
| 404 | K9O_COLLECTION_NOT_FOUND | The collection referenced in the subscription does not exist in this project. |
| 429 | K9O_SUBSCRIPTION_LIMIT_EXCEEDED | This project has reached its concurrent subscription limit; upgrade your plan or close an existing subscription before opening a new one. |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.realtime.subscribe()Showing example in TypeScript
"retry: 1000\n:ok\n\nid: evt_01hx8m3k2q9w4z7n5r6tab\nevent: row_inserted\ndata: {\"topic\":\"collections.orders.row_inserted\",\"eventType\":\"row_inserted\",\"payload\":{\"collection\":\"orders\",\"id\":\"42\"},\"occurredAt\":\"2026-11-02T14:05:31.512Z\",\"eventId\":\"evt_01hx8m3k2q9w4z7n5r6tab\"}\n\n"