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

Write Dataset Rows

Appends rows: the body is newline-delimited JSON or a JSON array.

Each row is validated against the dataset's schema; onError=skip (default) skips bad rows and reports them, onError=reject refuses the whole write (400 K9O_INGEST_SCHEMA_MISMATCH).

Returns ingested, skipped, up to 100 skippedDetails, the partitions touched and the bytes written.

Platform telemetry datasets cannot be written.

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.

Returns 503 K9O_ANALYTICS_UNAVAILABLE until the region's analytics storage is provisioned.

Parameters
datasetSlug *path

The Dataset's slug.

onErrorquery

What a row that doesn't conform does: skip (the default) writes the other rows and reports it in skippedDetails; reject refuses the whole write, so nothing is written.

projectSlug *path

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

It is unique within the org.

Request body
Responses
HTTPK9O CodeDescription
200Success
400K9O_INGEST_PARSE_FAILEDThe body is empty or not valid NDJSON / JSON, or `onError` is invalid.
400K9O_INGEST_SCHEMA_MISMATCHA row does not match the dataset's schema and `onError=reject`.
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:write.
403K9O_FORBIDDENPlatform telemetry datasets are read-only.
404K9O_NOT_FOUNDThe project was not found for this caller (project service tokens and extension tokens cannot call this endpoint).
404K9O_DATASET_NOT_FOUNDNo active dataset with this slug exists in the project.
503K9O_ANALYTICS_UNAVAILABLEThe region's analytics storage is not available yet; retry later.
Response body (200)
data *object

The result of the write: how many rows were written and skipped, and why.

ingested *integer

Rows written to the dataset.

skipped *integer

Rows not written: rows that don't match the dataset's declared columns, plus rows the dataset write refused.

skippedDetails *object[]

The skipped rows and why, at most 100.

Empty when nothing was skipped.

index *integer

The skipped row's position, counting from 0.

reason *string

Why the row was skipped, in plain text.

partitionsTouched *string[]

The partition paths written, region first, such as region=eu/occurred_at=2026-11-02.

Empty when nothing was written.

bytes *integer

Request body size.

bytesWritteninteger

Present when anything was written.

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.analytics.write('<datasetSlug>', {})

Showing example in TypeScript

Request example
[]
Response example (200)
{
  "data": {
    "ingested": 0,
    "skipped": 0,
    "skippedDetails": [
      {
        "index": 0,
        "reason": "string"
      }
    ],
    "partitionsTouched": [
      "string"
    ],
    "bytes": 0,
    "bytesWritten": 0
  },
  "meta": {
    "timing": {
      "gatewayMs": 0,
      "totalMs": 0
    },
    "context": {
      "requestId": "string",
      "traceId": "string",
      "projectId": "string"
    },
    "warnings": [
      {
        "code": "string",
        "message": "string"
      }
    ]
  }
}

More in Analytics & Intelligence