# Rollups Source: https://www.hotdata.dev/docs/api-reference/rollups Site index: https://www.hotdata.dev/llms.txt Declare rollups on a database's tables: pre-aggregated rows, one per time bucket and set of dimension values, that answer matching aggregate queries without reading the whole table. Queries use a rollup on their own when it can answer them, and their response says whether one was used. Declaring a rollup limits how the table's older rows can be changed: see the declare endpoint. ## List a database's rollups `GET /v1/databases/{database_id}/rollups` List the rollups on a database's tables. Filter by schema, or by schema and table. **Path parameters** | Name | Type | Description | | --- | --- | --- | | `database_id` *(required)* | `string` | Database ID | **Query parameters** | Name | Type | Description | | --- | --- | --- | | `schema_name` | `string` | Only rollups on tables of this schema | | `table_name` | `string` | Only rollups on this table; requires `schema_name` | **Response** `200` — The rollups | Name | Type | Description | | --- | --- | --- | | `rollups` *(required)* | `Rollup`[] | | **Fields of `rollups`** | Name | Type | Description | | --- | --- | --- | | `rollups[].bucket_width_secs` *(required)* | `integer` | Width of each time bucket, in seconds. | | `rollups[].covered_until` | `string` | End (exclusive) of the time range the rollup has built; null until the build's first step. Build progress, not freshness: queries also read the table for rows the rollup has not absorbed, so answers are the same either way. It advances while `building`, and after the table is replaced it describes the old table until the rollup is rebuilt. | | `rollups[].created_at` *(required)* | `string` | When the rollup was declared. | | `rollups[].database_id` *(required)* | `string` | Database that holds the table. | | `rollups[].dimensions` *(required)* | `string`[] | Columns rows are grouped by, besides the time bucket. | | `rollups[].error` | `string` | Why the build failed, when status is `build_failed`; null otherwise. | | `rollups[].failed_at` | `string` | When the build failed, when status is `build_failed`; null otherwise. | | `rollups[].filter` | `string` | Condition a row must pass to be kept; absent when every row is kept. | | `rollups[].id` *(required)* | `string` | Rollup ID. | | `rollups[].measures` *(required)* | `RollupMeasure`[] | The measures, as declared. | | `rollups[].measures[].centroids` | `integer` | For `approx_percentile` only: the summary's accuracy, as the `centroids` argument of `approx_percentile_cont`. Defaults to 100, at most 1000; a query uses the rollup only with the same value (100 when it omits one). Range: `1`–`1000` | | `rollups[].measures[].column` | `string` | Column to aggregate. Required for every kind except `count`, which counts all rows when it is omitted. | | `rollups[].measures[].kind` *(required)* | `"count"` or `"sum"` or `"min"` or `"max"` or `"numeric"` or `"approx_percentile"` | The aggregate a measure keeps. - `count`: number of rows, or with a `column`, rows where it is not null. - `sum`, `min`, `max`: that aggregate of `column`. - `numeric`: `count`, `sum`, `min` and `max` of `column`, enough to answer `count`, `sum`, `avg`, `min` and `max` queries on it. `avg` of a decimal column is always read from the table. - `approx_percentile`: a summary of `column` that answers `approx_percentile_cont` and `approx_median` queries at any percentile. Answers are approximate and can differ slightly from the same query on the table. Much larger than other measures, and grows with `centroids`. | | `rollups[].schema_name` *(required)* | `string` | Schema of the table. | | `rollups[].status` *(required)* | `RollupStatus` | A rollup's state. Queries use a rollup only when it is `ready`. - `building`: building its first rows. - `ready`: can answer queries. - `needs_rebuild`: a change to its table it cannot follow; it needs a rebuild. - `dropping`: being dropped. - `build_failed`: the build failed. Progress is kept; request a rebuild to resume. | | `rollups[].table_name` *(required)* | `string` | The table the rollup is declared on. | | `rollups[].time_column` *(required)* | `string` | Timestamp column rows are bucketed by. | | `rollups[].updated_at` *(required)* | `string` | When the rollup last changed. | | `rollups[].window_secs` | `integer` | How long, in seconds, after a row's time it can still be changed or deleted. Shared by every rollup on the table. Null when the table's state cannot be read, or the table was dropped and created again since the rollup was declared. | **Example response** ```json { "rollups": [ { "bucket_width_secs": 3600, "covered_until": "2026-11-18T16:00:00Z", "created_at": "2026-01-01T00:00:00Z", "database_id": "dbid01h9xyz", "dimensions": [ "region" ], "error": "string", "failed_at": "2026-01-01T00:00:00Z", "filter": "status <> 'error'", "id": "rlup01h9xyz", "measures": [ { "kind": "count" }, { "kind": "numeric", "column": "amount" } ], "schema_name": "public", "status": "building", "table_name": "events", "time_column": "ts", "updated_at": "2026-01-01T00:00:00Z", "window_secs": 3600 } ] } ``` **Errors** | Status | Description | | ------ | ----------- | | `400` | `table_name` without `schema_name` | | `404` | No such database | ## Declare a rollup on a table `POST /v1/databases/{database_id}/rollups` Declare a rollup: pre-aggregated rows of one table, one per time bucket and set of dimension values, which answer matching aggregate queries without reading the whole table. Answers are the same as reading the table. The table must hold data, and its time column must be a timestamp with no time zone or in UTC. The rollup starts as `building` and becomes `ready` when its build catches up with the table; poll the returned job or the rollup. When `job_id` is null the build could not be started: rebuild the rollup to start it. A query uses a ready rollup when it aggregates with `count`, `sum`, `avg`, `min`, `max`, or `approx_percentile_cont` / `approx_median` at the declared `centroids` (approximate answers only); groups by the time column in buckets that are a multiple of `bucket_width_secs`, and by dimensions; filters only on dimensions and the time column; and, when the rollup has a `filter`, contains each of its `AND`-joined parts written the same way. `min` and `max` of a floating-point column are always read from the table. The query's response says whether a rollup was used. Declaring a rollup changes how the table can be written. Rows whose time is older than `window_secs` can no longer be changed or deleted, and SQL `DELETE` and `UPDATE` on the table are refused: change rows with a keyed load whose key includes the time column. Appends are always allowed, and so is replacing the table, after which its rollups need a rebuild and queries read the table until then. A fork of the database does not carry rollups, and dropping the table drops them. A rollup cannot be changed: drop it and declare a new one, which builds from the start. **Path parameters** | Name | Type | Description | | --- | --- | --- | | `database_id` *(required)* | `string` | Database ID | **Request body** | Name | Type | Description | | --- | --- | --- | | `bucket_width_secs` *(required)* | `integer` | Width of each time bucket, in seconds. Buckets align to the Unix epoch, in UTC. A query uses the rollup when its own time buckets are a multiple of this width. Min: `1` | | `dimensions` | `string`[] | Columns to group by, besides the time bucket. A query can also filter on these columns and still use the rollup. | | `filter` | `string` | SQL condition a row must pass to be kept; omit it to keep every row. A query uses the rollup only when its `WHERE` clause contains each `AND`-joined part written the same way, and the condition must be deterministic (no subqueries, aggregates, `now()` or `random()`). | | `measures` *(required)* | `RollupMeasure`[] | Aggregates each rollup row keeps. | | `schema_name` *(required)* | `string` | Schema that holds the table. | | `table_name` *(required)* | `string` | Table to roll up. | | `time_column` *(required)* | `string` | Timestamp column to bucket rows by. It must have no time zone, or be in UTC. | | `window_secs` | `integer` | How long, in seconds, after a row's time it can still be changed or deleted; later edits are refused, appends are always allowed. Shared by every rollup on the table: the first sets it (default one hour), later ones must match or omit it. Min: `1` | **Fields of `measures`** | Name | Type | Description | | --- | --- | --- | | `measures[].centroids` | `integer` | For `approx_percentile` only: the summary's accuracy, as the `centroids` argument of `approx_percentile_cont`. Defaults to 100, at most 1000; a query uses the rollup only with the same value (100 when it omits one). Range: `1`–`1000` | | `measures[].column` | `string` | Column to aggregate. Required for every kind except `count`, which counts all rows when it is omitted. | | `measures[].kind` *(required)* | `"count"` or `"sum"` or `"min"` or `"max"` or `"numeric"` or `"approx_percentile"` | The aggregate a measure keeps. - `count`: number of rows, or with a `column`, rows where it is not null. - `sum`, `min`, `max`: that aggregate of `column`. - `numeric`: `count`, `sum`, `min` and `max` of `column`, enough to answer `count`, `sum`, `avg`, `min` and `max` queries on it. `avg` of a decimal column is always read from the table. - `approx_percentile`: a summary of `column` that answers `approx_percentile_cont` and `approx_median` queries at any percentile. Answers are approximate and can differ slightly from the same query on the table. Much larger than other measures, and grows with `centroids`. | **Example request** ```json { "bucket_width_secs": 3600, "dimensions": [ "region" ], "filter": "status <> 'error'", "measures": [ { "kind": "count" }, { "kind": "numeric", "column": "amount" } ], "schema_name": "public", "table_name": "events", "time_column": "ts", "window_secs": 3600 } ``` **Response** `201` — The rollup was declared | Name | Type | Description | | --- | --- | --- | | `job_id` | `string` | Background job that builds the rollup: poll `GET /v1/jobs/{job_id}` to follow it; the rollup becomes `ready` once the build catches up with the table. Null when the build could not be started: the rollup stays `building`, and rebuilding it starts the build. | | `rollup` *(required)* | `Rollup` | A rollup on a database's table: what it keeps, and its state. Queries use it only when `status` is `ready`. | **Fields of `rollup`** | Name | Type | Description | | --- | --- | --- | | `rollup.bucket_width_secs` *(required)* | `integer` | Width of each time bucket, in seconds. | | `rollup.covered_until` | `string` | End (exclusive) of the time range the rollup has built; null until the build's first step. Build progress, not freshness: queries also read the table for rows the rollup has not absorbed, so answers are the same either way. It advances while `building`, and after the table is replaced it describes the old table until the rollup is rebuilt. | | `rollup.created_at` *(required)* | `string` | When the rollup was declared. | | `rollup.database_id` *(required)* | `string` | Database that holds the table. | | `rollup.dimensions` *(required)* | `string`[] | Columns rows are grouped by, besides the time bucket. | | `rollup.error` | `string` | Why the build failed, when status is `build_failed`; null otherwise. | | `rollup.failed_at` | `string` | When the build failed, when status is `build_failed`; null otherwise. | | `rollup.filter` | `string` | Condition a row must pass to be kept; absent when every row is kept. | | `rollup.id` *(required)* | `string` | Rollup ID. | | `rollup.measures` *(required)* | `RollupMeasure`[] | The measures, as declared. | | `rollup.measures[].centroids` | `integer` | For `approx_percentile` only: the summary's accuracy, as the `centroids` argument of `approx_percentile_cont`. Defaults to 100, at most 1000; a query uses the rollup only with the same value (100 when it omits one). Range: `1`–`1000` | | `rollup.measures[].column` | `string` | Column to aggregate. Required for every kind except `count`, which counts all rows when it is omitted. | | `rollup.measures[].kind` *(required)* | `"count"` or `"sum"` or `"min"` or `"max"` or `"numeric"` or `"approx_percentile"` | The aggregate a measure keeps. - `count`: number of rows, or with a `column`, rows where it is not null. - `sum`, `min`, `max`: that aggregate of `column`. - `numeric`: `count`, `sum`, `min` and `max` of `column`, enough to answer `count`, `sum`, `avg`, `min` and `max` queries on it. `avg` of a decimal column is always read from the table. - `approx_percentile`: a summary of `column` that answers `approx_percentile_cont` and `approx_median` queries at any percentile. Answers are approximate and can differ slightly from the same query on the table. Much larger than other measures, and grows with `centroids`. | | `rollup.schema_name` *(required)* | `string` | Schema of the table. | | `rollup.status` *(required)* | `RollupStatus` | A rollup's state. Queries use a rollup only when it is `ready`. - `building`: building its first rows. - `ready`: can answer queries. - `needs_rebuild`: a change to its table it cannot follow; it needs a rebuild. - `dropping`: being dropped. - `build_failed`: the build failed. Progress is kept; request a rebuild to resume. | | `rollup.table_name` *(required)* | `string` | The table the rollup is declared on. | | `rollup.time_column` *(required)* | `string` | Timestamp column rows are bucketed by. | | `rollup.updated_at` *(required)* | `string` | When the rollup last changed. | | `rollup.window_secs` | `integer` | How long, in seconds, after a row's time it can still be changed or deleted. Shared by every rollup on the table. Null when the table's state cannot be read, or the table was dropped and created again since the rollup was declared. | **Example response** ```json { "job_id": "jobs01h9xyz", "rollup": { "bucket_width_secs": 3600, "covered_until": "2026-11-18T16:00:00Z", "created_at": "2026-01-01T00:00:00Z", "database_id": "dbid01h9xyz", "dimensions": [ "region" ], "error": "string", "failed_at": "2026-01-01T00:00:00Z", "filter": "status <> 'error'", "id": "rlup01h9xyz", "measures": [ { "kind": "count" }, { "kind": "numeric", "column": "amount" } ], "schema_name": "public", "status": "building", "table_name": "events", "time_column": "ts", "updated_at": "2026-01-01T00:00:00Z", "window_secs": 3600 } } ``` **Errors** | Status | Description | | ------ | ----------- | | `400` | The declaration does not fit the table | | `404` | No such database or table | | `409` | An identical rollup already exists, or the table's window differs | ## Get a rollup `GET /v1/databases/{database_id}/rollups/{rollup_id}` Get a rollup: its definition, its status, and how far its build has come. **Path parameters** | Name | Type | Description | | --- | --- | --- | | `database_id` *(required)* | `string` | Database ID | | `rollup_id` *(required)* | `string` | Rollup ID | **Response** `200` — The rollup | Name | Type | Description | | --- | --- | --- | | `bucket_width_secs` *(required)* | `integer` | Width of each time bucket, in seconds. | | `covered_until` | `string` | End (exclusive) of the time range the rollup has built; null until the build's first step. Build progress, not freshness: queries also read the table for rows the rollup has not absorbed, so answers are the same either way. It advances while `building`, and after the table is replaced it describes the old table until the rollup is rebuilt. | | `created_at` *(required)* | `string` | When the rollup was declared. | | `database_id` *(required)* | `string` | Database that holds the table. | | `dimensions` *(required)* | `string`[] | Columns rows are grouped by, besides the time bucket. | | `error` | `string` | Why the build failed, when status is `build_failed`; null otherwise. | | `failed_at` | `string` | When the build failed, when status is `build_failed`; null otherwise. | | `filter` | `string` | Condition a row must pass to be kept; absent when every row is kept. | | `id` *(required)* | `string` | Rollup ID. | | `measures` *(required)* | `RollupMeasure`[] | The measures, as declared. | | `schema_name` *(required)* | `string` | Schema of the table. | | `status` *(required)* | `RollupStatus` | A rollup's state. Queries use a rollup only when it is `ready`. - `building`: building its first rows. - `ready`: can answer queries. - `needs_rebuild`: a change to its table it cannot follow; it needs a rebuild. - `dropping`: being dropped. - `build_failed`: the build failed. Progress is kept; request a rebuild to resume. | | `table_name` *(required)* | `string` | The table the rollup is declared on. | | `time_column` *(required)* | `string` | Timestamp column rows are bucketed by. | | `updated_at` *(required)* | `string` | When the rollup last changed. | | `window_secs` | `integer` | How long, in seconds, after a row's time it can still be changed or deleted. Shared by every rollup on the table. Null when the table's state cannot be read, or the table was dropped and created again since the rollup was declared. | **Fields of `measures`** | Name | Type | Description | | --- | --- | --- | | `measures[].centroids` | `integer` | For `approx_percentile` only: the summary's accuracy, as the `centroids` argument of `approx_percentile_cont`. Defaults to 100, at most 1000; a query uses the rollup only with the same value (100 when it omits one). Range: `1`–`1000` | | `measures[].column` | `string` | Column to aggregate. Required for every kind except `count`, which counts all rows when it is omitted. | | `measures[].kind` *(required)* | `"count"` or `"sum"` or `"min"` or `"max"` or `"numeric"` or `"approx_percentile"` | The aggregate a measure keeps. - `count`: number of rows, or with a `column`, rows where it is not null. - `sum`, `min`, `max`: that aggregate of `column`. - `numeric`: `count`, `sum`, `min` and `max` of `column`, enough to answer `count`, `sum`, `avg`, `min` and `max` queries on it. `avg` of a decimal column is always read from the table. - `approx_percentile`: a summary of `column` that answers `approx_percentile_cont` and `approx_median` queries at any percentile. Answers are approximate and can differ slightly from the same query on the table. Much larger than other measures, and grows with `centroids`. | **Example response** ```json { "bucket_width_secs": 3600, "covered_until": "2026-11-18T16:00:00Z", "created_at": "2026-01-01T00:00:00Z", "database_id": "dbid01h9xyz", "dimensions": [ "region" ], "error": "string", "failed_at": "2026-01-01T00:00:00Z", "filter": "status <> 'error'", "id": "rlup01h9xyz", "measures": [ { "kind": "count" }, { "kind": "numeric", "column": "amount" } ], "schema_name": "public", "status": "building", "table_name": "events", "time_column": "ts", "updated_at": "2026-01-01T00:00:00Z", "window_secs": 3600 } ``` **Errors** | Status | Description | | ------ | ----------- | | `404` | No such database or rollup | ## Drop a rollup `DELETE /v1/databases/{database_id}/rollups/{rollup_id}` Drop a rollup and its rows. The table does not change. Returns once the rollup is gone, which can take up to two minutes when a build step is running on it. When the last rollup on a table is dropped, the table's write window no longer applies. **Path parameters** | Name | Type | Description | | --- | --- | --- | | `database_id` *(required)* | `string` | Database ID | | `rollup_id` *(required)* | `string` | Rollup ID | **Response** `204` — The rollup was dropped **Errors** | Status | Description | | ------ | ----------- | | `404` | No such database or rollup | ## Rebuild a rollup `POST /v1/databases/{database_id}/rollups/{rollup_id}/rebuild` Start building a rollup again, in the background, and return the build job. A `needs_rebuild` rollup (left that way when its table is replaced) is emptied and rebuilt; queries read the table until the build finishes. A `build_failed` rollup, or a `building` one whose build is not running, resumes where it stopped. **Path parameters** | Name | Type | Description | | --- | --- | --- | | `database_id` *(required)* | `string` | Database ID | | `rollup_id` *(required)* | `string` | Rollup ID | **Response** `202` — The build was started | Name | Type | Description | | --- | --- | --- | | `job_id` | `string` | Background job that builds the rollup: poll `GET /v1/jobs/{job_id}` to follow it; the rollup becomes `ready` once the build catches up with the table. Null when the build could not be started: the rollup stays `building`, and rebuilding it starts the build. | | `rollup` *(required)* | `Rollup` | A rollup on a database's table: what it keeps, and its state. Queries use it only when `status` is `ready`. | **Fields of `rollup`** | Name | Type | Description | | --- | --- | --- | | `rollup.bucket_width_secs` *(required)* | `integer` | Width of each time bucket, in seconds. | | `rollup.covered_until` | `string` | End (exclusive) of the time range the rollup has built; null until the build's first step. Build progress, not freshness: queries also read the table for rows the rollup has not absorbed, so answers are the same either way. It advances while `building`, and after the table is replaced it describes the old table until the rollup is rebuilt. | | `rollup.created_at` *(required)* | `string` | When the rollup was declared. | | `rollup.database_id` *(required)* | `string` | Database that holds the table. | | `rollup.dimensions` *(required)* | `string`[] | Columns rows are grouped by, besides the time bucket. | | `rollup.error` | `string` | Why the build failed, when status is `build_failed`; null otherwise. | | `rollup.failed_at` | `string` | When the build failed, when status is `build_failed`; null otherwise. | | `rollup.filter` | `string` | Condition a row must pass to be kept; absent when every row is kept. | | `rollup.id` *(required)* | `string` | Rollup ID. | | `rollup.measures` *(required)* | `RollupMeasure`[] | The measures, as declared. | | `rollup.measures[].centroids` | `integer` | For `approx_percentile` only: the summary's accuracy, as the `centroids` argument of `approx_percentile_cont`. Defaults to 100, at most 1000; a query uses the rollup only with the same value (100 when it omits one). Range: `1`–`1000` | | `rollup.measures[].column` | `string` | Column to aggregate. Required for every kind except `count`, which counts all rows when it is omitted. | | `rollup.measures[].kind` *(required)* | `"count"` or `"sum"` or `"min"` or `"max"` or `"numeric"` or `"approx_percentile"` | The aggregate a measure keeps. - `count`: number of rows, or with a `column`, rows where it is not null. - `sum`, `min`, `max`: that aggregate of `column`. - `numeric`: `count`, `sum`, `min` and `max` of `column`, enough to answer `count`, `sum`, `avg`, `min` and `max` queries on it. `avg` of a decimal column is always read from the table. - `approx_percentile`: a summary of `column` that answers `approx_percentile_cont` and `approx_median` queries at any percentile. Answers are approximate and can differ slightly from the same query on the table. Much larger than other measures, and grows with `centroids`. | | `rollup.schema_name` *(required)* | `string` | Schema of the table. | | `rollup.status` *(required)* | `RollupStatus` | A rollup's state. Queries use a rollup only when it is `ready`. - `building`: building its first rows. - `ready`: can answer queries. - `needs_rebuild`: a change to its table it cannot follow; it needs a rebuild. - `dropping`: being dropped. - `build_failed`: the build failed. Progress is kept; request a rebuild to resume. | | `rollup.table_name` *(required)* | `string` | The table the rollup is declared on. | | `rollup.time_column` *(required)* | `string` | Timestamp column rows are bucketed by. | | `rollup.updated_at` *(required)* | `string` | When the rollup last changed. | | `rollup.window_secs` | `integer` | How long, in seconds, after a row's time it can still be changed or deleted. Shared by every rollup on the table. Null when the table's state cannot be read, or the table was dropped and created again since the rollup was declared. | **Example response** ```json { "job_id": "jobs01h9xyz", "rollup": { "bucket_width_secs": 3600, "covered_until": "2026-11-18T16:00:00Z", "created_at": "2026-01-01T00:00:00Z", "database_id": "dbid01h9xyz", "dimensions": [ "region" ], "error": "string", "failed_at": "2026-01-01T00:00:00Z", "filter": "status <> 'error'", "id": "rlup01h9xyz", "measures": [ { "kind": "count" }, { "kind": "numeric", "column": "amount" } ], "schema_name": "public", "status": "building", "table_name": "events", "time_column": "ts", "updated_at": "2026-01-01T00:00:00Z", "window_secs": 3600 } } ``` **Errors** | Status | Description | | ------ | ----------- | | `404` | No such database or rollup | | `409` | The rollup is ready, is being dropped, or is already being built | ## Set a rollup's window `PUT /v1/databases/{database_id}/rollups/{rollup_id}/window` Set how long after a row's time it can still be changed or deleted. This applies to every rollup on the same table. Appends are always allowed. Nothing is rebuilt: a wider window applies as time passes, and a narrower one at the next refresh. **Path parameters** | Name | Type | Description | | --- | --- | --- | | `database_id` *(required)* | `string` | Database ID | | `rollup_id` *(required)* | `string` | Rollup ID | **Request body** | Name | Type | Description | | --- | --- | --- | | `window_secs` *(required)* | `integer` | How long, in seconds, after a row's time it can still be changed or deleted. Applies to every rollup on the table. Min: `1` | **Example request** ```json { "window_secs": 21600 } ``` **Response** `200` — The rollup, with its new window | Name | Type | Description | | --- | --- | --- | | `bucket_width_secs` *(required)* | `integer` | Width of each time bucket, in seconds. | | `covered_until` | `string` | End (exclusive) of the time range the rollup has built; null until the build's first step. Build progress, not freshness: queries also read the table for rows the rollup has not absorbed, so answers are the same either way. It advances while `building`, and after the table is replaced it describes the old table until the rollup is rebuilt. | | `created_at` *(required)* | `string` | When the rollup was declared. | | `database_id` *(required)* | `string` | Database that holds the table. | | `dimensions` *(required)* | `string`[] | Columns rows are grouped by, besides the time bucket. | | `error` | `string` | Why the build failed, when status is `build_failed`; null otherwise. | | `failed_at` | `string` | When the build failed, when status is `build_failed`; null otherwise. | | `filter` | `string` | Condition a row must pass to be kept; absent when every row is kept. | | `id` *(required)* | `string` | Rollup ID. | | `measures` *(required)* | `RollupMeasure`[] | The measures, as declared. | | `schema_name` *(required)* | `string` | Schema of the table. | | `status` *(required)* | `RollupStatus` | A rollup's state. Queries use a rollup only when it is `ready`. - `building`: building its first rows. - `ready`: can answer queries. - `needs_rebuild`: a change to its table it cannot follow; it needs a rebuild. - `dropping`: being dropped. - `build_failed`: the build failed. Progress is kept; request a rebuild to resume. | | `table_name` *(required)* | `string` | The table the rollup is declared on. | | `time_column` *(required)* | `string` | Timestamp column rows are bucketed by. | | `updated_at` *(required)* | `string` | When the rollup last changed. | | `window_secs` | `integer` | How long, in seconds, after a row's time it can still be changed or deleted. Shared by every rollup on the table. Null when the table's state cannot be read, or the table was dropped and created again since the rollup was declared. | **Fields of `measures`** | Name | Type | Description | | --- | --- | --- | | `measures[].centroids` | `integer` | For `approx_percentile` only: the summary's accuracy, as the `centroids` argument of `approx_percentile_cont`. Defaults to 100, at most 1000; a query uses the rollup only with the same value (100 when it omits one). Range: `1`–`1000` | | `measures[].column` | `string` | Column to aggregate. Required for every kind except `count`, which counts all rows when it is omitted. | | `measures[].kind` *(required)* | `"count"` or `"sum"` or `"min"` or `"max"` or `"numeric"` or `"approx_percentile"` | The aggregate a measure keeps. - `count`: number of rows, or with a `column`, rows where it is not null. - `sum`, `min`, `max`: that aggregate of `column`. - `numeric`: `count`, `sum`, `min` and `max` of `column`, enough to answer `count`, `sum`, `avg`, `min` and `max` queries on it. `avg` of a decimal column is always read from the table. - `approx_percentile`: a summary of `column` that answers `approx_percentile_cont` and `approx_median` queries at any percentile. Answers are approximate and can differ slightly from the same query on the table. Much larger than other measures, and grows with `centroids`. | **Example response** ```json { "bucket_width_secs": 3600, "covered_until": "2026-11-18T16:00:00Z", "created_at": "2026-01-01T00:00:00Z", "database_id": "dbid01h9xyz", "dimensions": [ "region" ], "error": "string", "failed_at": "2026-01-01T00:00:00Z", "filter": "status <> 'error'", "id": "rlup01h9xyz", "measures": [ { "kind": "count" }, { "kind": "numeric", "column": "amount" } ], "schema_name": "public", "status": "building", "table_name": "events", "time_column": "ts", "updated_at": "2026-01-01T00:00:00Z", "window_secs": 3600 } ``` **Errors** | Status | Description | | ------ | ----------- | | `400` | The window is zero or too large | | `404` | No such database or rollup | | `409` | The rollup is being dropped, or its table was replaced |