/analytics/{datasetSlug}/readRead Dataset Rows
Pages through a dataset's rows.
Body: optional partitionFilter (constraints on declared partition keys), cursor and limit (clamped to a page maximum).
Each row carries a stable _k9o_row_id; meta.cursor.next continues, and the first page includes meta.schema.
Requires the PROJECT_ADMIN, PROJECT_AUTHOR or PROJECT_EDITOR role and the datasets:query permission on every dataset it reads.
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.
| datasetSlug * | path | The Dataset's slug. |
| projectSlug * | path | The project's slug: the path segment after It is unique within the org. |
| partitionFilter | object | Keys are declared partition columns. |
| cursor | string |
|
| limit | integer | Default 1000; above 10000 is clamped (with a |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | Success | |
| 400 | K9O_ANALYTICS_READ_INVALID | The dataset slug or the body (`limit`, `cursor`, `partitionFilter`) is malformed. |
| 400 | K9O_ANALYTICS_UNKNOWN_PARTITION_KEY | `partitionFilter` names a key the dataset does not partition on. |
| 400 | K9O_ANALYTICS_CURSOR_INVALID | The cursor is invalid, expired, or was issued for another request. |
| 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_RBAC_DENY | Only PROJECT_ADMIN, PROJECT_AUTHOR and PROJECT_EDITOR may query datasets. |
| 403 | K9O_IAM_POLICY_DENIED | The caller's role or IAM policy does not grant datasets:query. |
| 403 | K9O_FORBIDDEN | Extension tokens cannot read datasets through this endpoint. |
| 404 | K9O_DATASET_NOT_FOUND | No active dataset with this slug exists in the project. |
| 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[] | One page of rows. |
| _k9o_row_id * | string | Stable id over the row's rendered values. |
| meta * | object | |
| 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 | |
| cursor * | object | |
| next * | any | |
| One of: string | ||
| or: null | ||
| schema | object[] | The declared columns; on the first page only. |
| name * | string | The column's name. |
| type * | string |
|
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.analytics.read('<datasetSlug>', {})Showing example in TypeScript
{
"cursor": "string",
"limit": 0
}{
"data": [
{
"_k9o_row_id": "string"
}
],
"meta": {
"timing": {
"gatewayMs": 0,
"totalMs": 0
},
"context": {
"requestId": "string",
"traceId": "string",
"projectId": "string"
},
"warnings": [
{
"code": "string",
"message": "string"
}
],
"cursor": {
"next": "string"
},
"schema": [
{
"name": "string",
"type": "string"
}
]
}
}