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

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

Parameters
rollupSlug *path

The rollup's slug: 1 to 63 lowercase letters, digits and hyphens.

fromquery

The start of the range, an ISO 8601 instant (inclusive, compared with each cell's window start).

Default 24 hours before to.

Must be before to.

toquery

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.

dimsquery

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 count, sum, min or max.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Responses
HTTPK9O CodeDescription
200Success
400K9O_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.
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.
500K9O_QUERY_EXECUTION_FAILEDThe query failed while running.
503K9O_ANALYTICS_UNAVAILABLEThe region's analytics storage is not available yet; retry later.
Response body (200)
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 measures.

agg *string

count, last, sum, avg, min, max, count_distinct, p50, p95 or p99.

columnstring

The source field aggregated.

Absent for count.

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 status and reason instead of measures.

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 ?dims= when the read projects.

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 count, sum, avg, min, max, count_distinct or percentile measure is a number, or null when the cell has no value.

A last measure is the stored value as the dataset query returns it, or null.

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 ?dims= when the read projects.

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 cohort_below_k: the cell's cohort is smaller than k.

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 dims projection left out: a withheld cell can't be combined into a coarser one.

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
projectIdstring
warningsobject[]
code *string
message *string
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.rollups.read('<rollupSlug>')

Showing example in TypeScript

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

More in Analytics & Intelligence