Skip to main content
GET/realtime/subscribe

Subscribe 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 topic
  • K9O_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.

Parameters
projectSlug *path

The project's slug, as in /@<projectSlug>/….

topicquery

Required.

The topic to listen on: an exact topic or a prefix ending in .* under collections., studio.workflows.runs., studio.queries.executed., studio.dashboards.refresh., forge.functions.invocations. or audit.project..

A missing or unknown topic answers 400 K9O_INVALID_FILTER.

filterquery

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 eq (a bare null means is: null).

An operator object ANDs its operators, for example:

{ "amount": { "gte": 1000, "lt": 5000 }, "status": { "in": ["paid", "shipped"] } }

Operators: eq, neq, gt, gte, lt, lte, in, notIn, like, ilike, is, contains, containedBy, rangeGt, rangeLt, overlaps, match, jsonPath.

Operands:

  • in and notIn take a non-empty array of strings, numbers or booleans with no commas inside an item.
  • is takes null, true or false.
  • contains and containedBy take any JSON value.
  • Every other operator takes a string, number or boolean (a range, array or JSON path literal as a string).

not negates the operators inside it, as the collection read's not. prefix does: { "status": { "not": { "in": ["cancelled"] } } } keeps the rows whose status is not cancelled.

As on a read, a NULL column never matches a negated comparison (use { "not": { "is": null } } for the non-NULL rows), and not can't be nested.

Not supported: or, joins and aggregates.

Valid only on a collections.<name>.* (or collections.<name>.<eventType>) topic.

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 K9O_INVALID_FILTER before the stream opens, with context.key naming the column, context.op the operator where one is at fault, and context.reason the cause:

malformed, not_an_object, empty, empty_condition, too_many_keys, too_many_conditions, array_value, unsupported_operator, not_supported, invalid_operand, topic_not_filterable, unknown_column, encrypted_column, field_protected_column, masked_column, column_grant_denied or value_type_mismatch.

A match pattern may be at most 256 characters and a jsonPath at most 512 (operand_too_long).

A pattern, path, range or array literal Postgres can't read is invalid_operand.

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 event: error with a code and closes, and that batch is not delivered:

  • { "code": "K9O_QUERY_TIMEOUT" }: the check ran past the time limit.
  • { "code": "K9O_INVALID_FILTER" }: the filter no longer holds (a filtered column has become one you can't read as plaintext, or the database refuses the filter).
  • { "code": "K9O_REALTIME_FILTER_UNAVAILABLE" }: the check failed for a transient reason (the database was briefly unavailable).

Re-read current state, then subscribe again: with a filter that holds after K9O_INVALID_FILTER, or the same one after the other two.

The filter applies to every row event but row_deleted, which can't be checked against it (the row is gone), so a filtered subscription receives the deletes of every row it can read on the topic, including rows that never matched.

fromSequencequery

The resume cursor, an eventId from an earlier frame, used when no Last-Event-ID header is sent.

Omitted, the stream starts with the recent events the server holds.

Responses
HTTPK9O CodeDescription
200A Server-Sent Events stream of the project's live events on `topic`.
400K9O_INVALID_FILTERThe 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.
401K9O_SESSION_EXPIREDYour session has expired; sign in again to establish a new subscription.
401K9O_INVALID_CREDENTIALSThe credentials provided are not valid; the subscription could not be opened.
403K9O_ACCESS_DENIEDYour role does not permit subscribing to this resource.
403K9O_RBAC_DENYThe audit topics (audit.project.*) need GET /audit-log's authority: PROJECT_AUDITOR or PROJECT_ADMIN (or an org admin or owner).
403K9O_IAM_POLICY_DENIEDThe bound IAMPolicy ceiling denies audit_log:query, which the audit topics (audit.project.*) require.
404K9O_COLLECTION_NOT_FOUNDThe collection referenced in the subscription does not exist in this project.
429K9O_SUBSCRIPTION_LIMIT_EXCEEDEDThis project has reached its concurrent subscription limit; upgrade your plan or close an existing subscription before opening a new one.
Response body (200)
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.realtime.subscribe()

Showing example in TypeScript

Response example (200)
"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"

More in Realtime Feeds & Streams