/rollups/{rollupSlug}/readRead Rollup
Returns the rollup's cells for a time range.
Query: from and to (ISO 8601; default the last 24 hours, at most 50,000 cells) and dims (a comma-separated projection; only count, sum, min and max measures combine).
Cells below the cohort threshold come back as {status: "suppressed", reason: "cohort_below_k"}; coverage reports the range, the last fold and whether it is complete.
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.
Returns 503 K9O_ANALYTICS_UNAVAILABLE until the region's analytics storage is provisioned.
| rollupSlug * | path | The rollup's slug: 1 to 63 lowercase letters, digits and hyphens. |
| from | query | The start of the range, an ISO 8601 instant (inclusive, compared with each cell's window start). Default 24 hours before Must be before |
| to | query | The end of the range, an ISO 8601 instant (exclusive). Default: the time of the request. A range holding more than 50,000 cells is refused. |
| dims | query | A comma-separated subset of the rollup's dimensions to group the cells by; empty groups by window alone. Omit it for every declared dimension. A projection onto fewer dimensions works only when every measure is |
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | Success | |
| 400 | K9O_INVALID_FIELD_VALUE | `from`/`to` are invalid or the range exceeds 50,000 cells, or `dims` is invalid or projects a measure that cannot be combined. |
| 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. |
| 500 | K9O_QUERY_EXECUTION_FAILED | The query failed while running. |
| 503 | K9O_ANALYTICS_UNAVAILABLE | The region's analytics storage is not available yet; retry later. |
| data * | object | The rollup's cells over the requested range. |
| rollup * | object | The rollup that was read. |
| slug * | string | The rollup's slug. |
| windowSeconds * | integer | The length of each window, in seconds. |
| dimensions * | string[] | The declared dimensions. |
| measures * | object[] | The declared measures. |
| name * | string | The measure's name: its key in each cell's |
| agg * | string |
|
| column | string | The source field aggregated. Absent for |
| k * | integer | The k-anonymity threshold a per-subject cell must meet. |
| cells * | any[] | The cells in the range, oldest window first. A suppressed cell carries |
| One of: object | ||
| bucket * | string <date-time> | The window start. |
| dims * | object | The cell's dimension values, one key per dimension: every declared dimension, or only those named in Each value is the stored value of that dimension column as the dataset query returns it, or null when the cell has none. |
| measures * | object | The cell's measure values, one key per declared measure name. A A Absent on a suppressed cell. |
| or: object | ||
| bucket * | string <date-time> | The window start. |
| dims * | object | The cell's dimension values, one key per dimension: every declared dimension, or only those named in Each value is the stored value of that dimension column as the dataset query returns it, or null when the cell has none. |
| status * | "suppressed" | The cell is withheld: too few people are in it. |
| reason * | "cohort_below_k" | Always |
| coverage * | object | What the answer covers. |
| from * | string <date-time> | The start of the range that was read. |
| to * | string <date-time> | The end of the range that was read (exclusive). |
| lastFoldAt * | any | When the rollup last folded new events into cells. Null when it never has. |
| One of: string <date-time> | ||
| or: null | ||
| complete * | boolean | True when the last fold succeeded and covered the whole range, so no cell in it is still to change. |
| excludedSuppressedCells * | integer | How many suppressed cells a Always 0 without a projection. |
| meta * | object | Request metadata: cost, timing and correlation ids. |
| cost * | object | Metered usage for this request; empty when nothing was metered. |
| timing * | object | |
| gatewayMs * | number | |
| totalMs * | number | |
| context * | object | |
| requestId * | string | |
| traceId * | string | |
| projectId | string | |
| warnings | object[] | |
| code * | string | |
| message * | string | |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.rollups.read('<rollupSlug>')Showing example in TypeScript
{
"data": {
"rollup": {
"slug": "string",
"windowSeconds": 0,
"dimensions": [
"string"
],
"measures": [
{
"name": "string",
"agg": "string",
"column": "string"
}
]
},
"k": 0,
"cells": [
{
"bucket": "string"
}
],
"coverage": {
"from": "string",
"to": "string",
"lastFoldAt": "string",
"complete": false,
"excludedSuppressedCells": 0
}
},
"meta": {
"timing": {
"gatewayMs": 0,
"totalMs": 0
},
"context": {
"requestId": "string",
"traceId": "string",
"projectId": "string"
},
"warnings": [
{
"code": "string",
"message": "string"
}
]
}
}