Skip to main content
GET/rollups/{rollupSlug}/subscribe

Subscribe 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.

Parameters
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.

Responses
HTTPK9O CodeDescription
200A 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`.
401K9O_UNAUTHENTICATEDThe caller is not signed in.
403K9O_ACCESS_DENIEDThe caller is not a member of this project; an organization role alone does not grant access.
403K9O_IAM_POLICY_DENIEDThe caller's role or IAM policy does not grant datasets:read.
404K9O_NOT_FOUNDNo rollup with this slug exists in the project.
404K9O_DATASET_NOT_FOUNDNo active dataset with this slug exists in the project.
409K9O_STATE_CONFLICTThe rollup's per-subject data cannot be served: a subject declaration or the cohort marker is missing.
429K9O_SUBSCRIPTION_LIMIT_EXCEEDEDThe caller already has the maximum number of open streams.
Response body (200)
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.rollups.subscribe('<rollupSlug>')

Showing example in TypeScript

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

More in Analytics & Intelligence