/rollups/{rollupSlug}/subscribeSubscribe to Rollup
Opens a server-sent events stream with one cell event per closed cell.
Resume with the Last-Event-ID header or fromSequence; a position that can no longer be resumed sends a resync event (re-read with the read endpoint).
The stream sends heartbeats, ends when the access token expires, and re-checks access while open.
Suppressed cells have their dimension values removed.
At most a fixed number of open streams per caller (429 K9O_SUBSCRIPTION_LIMIT_EXCEEDED).
Requires datasets:read on the rollup's dataset and datasets:query.
Callers must be members of the project (an organization role alone does not grant access); project service tokens and extension tokens cannot call it.
| rollupSlug * | path | The rollup's slug: 1 to 63 lowercase letters, digits and hyphens. |
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | A server-sent event stream of the rollup's cells as each window closes and is folded. It opens with `retry: <ms>` and a `:ok` comment. Each cell is one `cell` event: `id:` is the event id (send it back as `Last-Event-ID`, or as `?fromSequence=`, to resume), and `data:` is JSON `{ topic, eventType, payload, occurredAt, eventId }` where `topic` is `rollups.<slug>`, `eventType` is `cell`, and `payload` is `{ cellKey, bucket, dims, measures, final }`: - `cellKey` is the bucket then the dimension values, `|`-joined. - `bucket` is the window start in ISO 8601. - `dims` and `measures` are keyed like a read's cells. - `final` is true. A per-subject cell below the k threshold arrives as `{ cellKey, bucket, dims, status: "suppressed", reason: "cohort_below_k", final }` with every `dims` value null and no measures. When the resume cursor is unknown or no longer retained, an `event: resync` arrives (plus `head` on an eviction): ```text data: {"reason":"cursor-unknown"|"cursor-evicted","action":"reread-source"} ``` Read the rollup again, then keep listening. `:hb` comments keep a quiet stream open and `:dropped <n>` says n events were dropped for a slow reader. The stream ends when the caller's token expires, its session or access is revoked, or the server's maximum stream time passes. Reconnect with `Last-Event-ID`. | |
| 401 | K9O_UNAUTHENTICATED | The caller is not signed in. |
| 403 | K9O_ACCESS_DENIED | The caller is not a member of this project; an organization role alone does not grant access. |
| 403 | K9O_IAM_POLICY_DENIED | The caller's role or IAM policy does not grant datasets:read. |
| 404 | K9O_NOT_FOUND | No rollup with this slug exists in the project. |
| 404 | K9O_DATASET_NOT_FOUND | No active dataset with this slug exists in the project. |
| 409 | K9O_STATE_CONFLICT | The rollup's per-subject data cannot be served: a subject declaration or the cohort marker is missing. |
| 429 | K9O_SUBSCRIPTION_LIMIT_EXCEEDED | The caller already has the maximum number of open streams. |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.rollups.subscribe('<rollupSlug>')Showing example in TypeScript
"retry: 1000\n:ok\n\nid: evt_7Qm2k9x4Lz\nevent: cell\ndata: {\"topic\":\"rollups.orders-by-country\",\"eventType\":\"cell\",\"payload\":{\"cellKey\":\"2026-11-15T10:00:00.000Z|DE\",\"bucket\":\"2026-11-15T10:00:00.000Z\",\"dims\":{\"country\":\"DE\"},\"final\":true,\"measures\":{\"orders\":42}},\"occurredAt\":\"2026-11-15T11:00:02.114Z\",\"eventId\":\"evt_7Qm2k9x4Lz\"}\n\n"