/analytics/{datasetSlug}/rollupsCreate Rollup
Creates a continuous rollup that folds a stream into this dataset over fixed windows.
Body:
slug.source.dimensions(up to 16).measures(up to 64;count, orlast,sum,avg,min,max,count_distinct,p50,p95,p99over a column).windowSeconds(at least 60).reattestIntervalDays(7, 30, 90 or 365; default 90).- Exactly one of
subjectField(per-subject data, suppressed below the cohort threshold) ornonPersonal: true.
The rollup keeps running only while its configuration is re-attested within the interval.
Returns the rollup and its read and subscribe endpoints.
Requires the datasets:write permission (PROJECT_ADMIN or PROJECT_AUTHOR by default).
Callers must be members of the project (an organization role alone does not grant access); project service tokens and extension tokens cannot call it.
| datasetSlug * | path | The Dataset's slug. |
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| slug * | string | The rollup's slug: 1 to 63 lowercase letters, digits and hyphens, unique in the project. It can't be changed later; the rollup's read and subscribe paths use it. |
| subjectField | string | The source event field that names the data subject: letters, digits and underscores, not starting with a digit. With it, each cell counts distinct subjects and a cell with too few is suppressed; the target dataset must then be a shared dataset that declares a Send this or |
| nonPersonal | boolean | Send Send this or |
| source * | string | The stream to fold: the slug of a Pulse Stream in this project, or |
| dimensions | string[] | The source fields each cell is grouped by: at most 16, unique, each letters, digits and underscores, not starting with a digit. Omit it for one cell per window. |
| measures * | object[] | What each cell computes: 1 to 64 measures. |
| name * | string | The measure's name: letters, digits and underscores, not starting with a digit, unique in the rollup. It is the measure's key in each cell. |
| agg * | string | The aggregation: |
| column | string | The source field to aggregate. Required for every aggregation except |
| windowSeconds * | integer | The width of each cell's time window, in seconds. At least 60. |
| reattestIntervalDays | any | How many days each attestation lasts: 7, 30, 90 or 365. Default 90. When it runs out, the rollup stops folding until someone re-attests it. |
| One of: 7 | ||
| or: 30 | ||
| or: 90 | ||
| or: 365 | ||
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | Success | |
| 400 | K9O_INVALID_REQUEST_SHAPE | The request body does not match the schema. |
| 400 | K9O_INVALID_FIELD_VALUE | A field is invalid: slug, source, dimensions, measures, window, re-attest interval, or neither / both of `subjectField` and `nonPersonal`. |
| 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:write. |
| 404 | K9O_NOT_FOUND | The project was not found for this caller (project service tokens and extension tokens cannot call this endpoint). |
| 404 | K9O_DATASET_NOT_FOUND | No active dataset with this slug exists in the project. |
| 409 | K9O_ALREADY_EXISTS | A rollup with this slug already exists. |
| 409 | K9O_PENDING_CHANGE_ALREADY_EXISTS | A rollup for this dataset and source already exists. |
| data * | object | A rollup, the state of its folding, and the paths to read it. |
| id * | string |
|
| slug * | string | The rollup's slug, unique in the project. Its read and subscribe paths use it. |
| subjectField * | any | The source event field that names the data subject. Null when the rollup declares |
| One of: string | ||
| or: null | ||
| nonPersonal * | boolean | True when the rollup's creator declared that its source carries no personal data. |
| datasetSlug * | string | The dataset the rollup writes to. |
| source * | string | The source the rollup folds: a Pulse Stream's slug, or a telemetry signal name. Falls back to the stored stream id when the stream has been deleted. |
| dimensions * | string[] | The fields each cell is grouped by, in declared order (at most 16). |
| measures * | object[] | The declared measures, in order (at most 64). |
| name * | string | The measure's name: its key in each cell's |
| agg * | string |
|
| column | string | The source field aggregated. Absent for |
| windowSeconds * | integer | The width of each cell's time window, in seconds. |
| enabled * | boolean | Whether the rollup is set to fold. |
| reattestIntervalDays * | integer | How many days each attestation lasts: 7, 30, 90 or 365. |
| attestedAt * | string <date-time> | When a person last confirmed the rollup (created or re-attested it). |
| expiresAt * | string <date-time> |
After it the rollup stops folding until it is re-attested. |
| attestationStatus * | "active" | "expiring_soon" | "expired" |
|
| cursorSequence * | any | The source sequence the last committed fold reached, as a decimal string. Null until a fold has written a cell. |
| One of: string | ||
| or: null | ||
| lastFoldAt * | any | When the last fold ran. Null if it has never run. |
| One of: string <date-time> | ||
| or: null | ||
| lastFoldStatus * | any | How the last fold ended: Null if it has never run. |
| One of: string | ||
| or: null | ||
| createdAt * | string <date-time> | When the rollup was created. |
| endpoints * | object | Absolute paths: |
| read * | string | The path to read the rollup's cells. |
| subscribe * | string | The path to subscribe to the rollup's cells as they change. |
| 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.analytics.rollups.create('<datasetSlug>', {})Showing example in TypeScript
{
"slug": "string",
"subjectField": "string",
"nonPersonal": false,
"source": "string",
"dimensions": [
"string"
],
"measures": [
{
"name": "string",
"agg": "string",
"column": "string"
}
],
"windowSeconds": 0,
"reattestIntervalDays": 7
}{
"data": {
"id": "string",
"slug": "string",
"subjectField": "string",
"nonPersonal": false,
"datasetSlug": "string",
"source": "string",
"dimensions": [
"string"
],
"measures": [
{
"name": "string",
"agg": "string",
"column": "string"
}
],
"windowSeconds": 0,
"enabled": false,
"reattestIntervalDays": 0,
"attestedAt": "string",
"expiresAt": "string",
"attestationStatus": "active",
"cursorSequence": "string",
"lastFoldAt": "string",
"lastFoldStatus": "string",
"createdAt": "string",
"endpoints": {
"read": "string",
"subscribe": "string"
}
},
"meta": {
"timing": {
"gatewayMs": 0,
"totalMs": 0
},
"context": {
"requestId": "string",
"traceId": "string",
"projectId": "string"
},
"warnings": [
{
"code": "string",
"message": "string"
}
]
}
}