Skip to main content
POST/analytics/{datasetSlug}/read

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

Parameters
datasetSlug *path

The Dataset's slug.

projectSlug *path

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

It is unique within the org.

Request body
partitionFilterobject

Keys are declared partition columns.

cursorstring

meta.cursor.next from the previous page.

limitinteger

Default 1000; above 10000 is clamped (with a query_limit_clamped warning).

Responses
HTTPK9O CodeDescription
200Success
400K9O_ANALYTICS_READ_INVALIDThe dataset slug or the body (`limit`, `cursor`, `partitionFilter`) is malformed.
400K9O_ANALYTICS_UNKNOWN_PARTITION_KEY`partitionFilter` names a key the dataset does not partition on.
400K9O_ANALYTICS_CURSOR_INVALIDThe cursor is invalid, expired, or was issued for another request.
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_RBAC_DENYOnly PROJECT_ADMIN, PROJECT_AUTHOR and PROJECT_EDITOR may query datasets.
403K9O_IAM_POLICY_DENIEDThe caller's role or IAM policy does not grant datasets:query.
403K9O_FORBIDDENExtension tokens cannot read datasets through this endpoint.
404K9O_DATASET_NOT_FOUNDNo active dataset with this slug exists in the project.
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[]

One page of rows. meta.cursor.next holds the cursor for the next page, or null on the last page.

_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
projectIdstring
warningsobject[]
code *string
message *string
cursor *object
next *any
One of: string
or: null
schemaobject[]

The declared columns; on the first page only.

name *string

The column's name.

type *string

string, int32, int64, float64, bool, date, timestamp, json, bytes, or decimal(p,s).

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.analytics.read('<datasetSlug>', {})

Showing example in TypeScript

Request example
{
  "cursor": "string",
  "limit": 0
}
Response example (200)
{
  "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"
      }
    ]
  }
}

More in Analytics & Intelligence