# Subscribe to Realtime Feed

`GET /realtime/subscribe` · Core · Realtime Feeds & Streams

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:

```json
{"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

| Name | In | Required | Description |
|---|---|---|---|
| `projectSlug` | path | yes | The project's slug, as in `/@<projectSlug>/…`. Example: `"storefront"`. |
| `topic` | query | no | 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`. |
| `filter` | query | no | 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: ```json { "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. |
| `fromSequence` | query | no | 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

- **200**: A Server-Sent Events stream of the project's live events on `topic`.

## Errors

| HTTP | Code | When |
|---|---|---|
| 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. |
| 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. |
| 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. |
| 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. |

## Code samples

### cURL

```bash
curl -X GET 'https://<org>.api-<region>.k9o.io/@storefront/realtime/subscribe' \
  -H 'Authorization: Bearer $K9O_TOKEN'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/realtime/subscribe', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`
  },
});
const { data, meta } = await res.json();
```

### @k9o/core

```typescript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.realtime.subscribe()
```

### k9o

```python
# k9o = create_client(org_slug="playground", project_slug="storefront", api_key="k9o_…")
response = k9o.realtime.subscribe()
```

### sdk-go

```go
// ctx := context.Background()
// client, _ := k9o.NewClient(k9o.ClientOpts{OrgSlug: "playground", ProjectSlug: "storefront", APIKey: "k9o_…"})
data, _, kerr := client.Realtime.Subscribe(ctx)
```

### k9o

```rust
// let k9o = Client::new(ClientOpts { org_slug: "playground".into(), project_slug: "storefront".into(), api_key: "k9o_…".into() })?;
let resp = k9o.realtime.subscribe().await?
```

### dev.k9o:core

```java
// K9o k9o = K9o.createClient(K9o.Opts.builder().orgSlug("playground").projectSlug("storefront").apiKey("k9o_…").build());
var response = k9o.realtime().subscribe()
```

### K9o.Core

```c#
// var k9o = K9oClient.Create(new K9oOptions { OrgSlug = "playground", ProjectSlug = "storefront", ApiKey = "k9o_…" });
var response = await k9o.Realtime.SubscribeAsync()
```

### k9o

```ruby
# k9o = K9o.create_client(org_slug: "playground", project_slug: "storefront", api_key: "k9o_…")
response = k9o.realtime.subscribe()
```

### k9o/sdk

```php
// $k9o = K9oClient::create(['org_slug' => 'playground', 'project_slug' => 'storefront', 'api_key' => 'k9o_…']);
$response = $k9o->realtime->subscribe()
```

### K9o

```swift
// let k9o = try K9o.createClient(orgSlug: "playground", projectSlug: "storefront", apiKey: "k9o_…")
let result = try await k9o.realtime.subscribe()
```

### core-kotlin

```kotlin
// val k9o = createClient { orgSlug = "playground"; projectSlug = "storefront"; apiKey = "k9o_…" }
val result = k9o.realtime.subscribe()
```

### k9o (Flutter)

```dart
// final k9o = K9o.createClient(orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…');
final result = await k9o.realtime.subscribe()
```

### @k9o/react-native

```javascript
// const k9o = createClient({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })  // RN, secure storage
const { data } = await k9o.realtime.subscribe()
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/subscribe-to-realtime-feed
