/analytics/{datasetSlug}/uploadUpload File
Uploads a CSV or JSON file (raw body, or multipart with file and an optional manifest), up to 25 MiB.
Query: format (csv or json, required), dryRun, onError, and for CSV delimiter, encoding and hasHeader. dryRun returns the detected columns and a 50-row preview without writing.
A manifest on a slug that does not exist yet creates the dataset and loads the file in one call.
Returns the ingest counts; the original file is kept for download.
Requires the datasets:write permission (PROJECT_ADMIN or PROJECT_AUTHOR by default).
A dry run or a manifest create needs datasets:create.
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. |
| file * | string <binary> | The CSV or JSON file ( |
| manifest | string | JSON: creates the dataset from this definition, then ingests the file. Omit it to append to an existing dataset. |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | Success | |
| 400 | K9O_INGEST_PARSE_FAILED | The file cannot be parsed, exceeds 25 MiB, or a query parameter or the manifest is invalid. |
| 400 | K9O_INGEST_SCHEMA_MISMATCH | A row does not match the dataset's schema and `onError=reject`. |
| 400 | K9O_DATASET_INVALID | The manifest is invalid, or the dataset already exists. |
| 400 | K9O_DATASET_STORAGE_TARGET_INVALID | The manifest's storage location does not exist or is retired. |
| 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_IAM_POLICY_DENIED | The caller's role or IAM policy does not grant datasets:write. |
| 403 | K9O_FORBIDDEN | Platform telemetry datasets are read-only. |
| 404 | K9O_NOT_FOUND | The project was not found for this caller (project service tokens and extension tokens cannot call this endpoint). |
| 404 | K9O_DATASET_NOT_FOUND | No active dataset with this slug exists in the project. |
| 429 | K9O_DATASET_LIMIT_EXCEEDED | The project already has the maximum number of datasets (200). |
| 503 | K9O_ANALYTICS_UNAVAILABLE | The region's analytics storage is not available yet; retry later. |
| data * | any |
|
| One of: object | ||
| dryRun * | true | Always true: nothing was written. |
| detected * | object | How the file was read. |
| encoding * | "utf-8" | "utf-8-bom" | "latin-1" | "windows-1252" | The file's text encoding: detected, or the |
| delimiter | "," | ";" | "\t" | The CSV field delimiter: detected from the header line, or the Absent for JSON. |
| format * | "csv" | "json" | The file format, from |
| columns * | object[] | The proposed columns, in file order. Review them, then create the dataset with them (or send them as the |
| sourceName * | string | The column's name in the file: the CSV header cell, |
| name * | string | The proposed column name: |
| type * | string | The proposed column type: the narrowest type every non-empty sampled value fits, or |
| nullable * | boolean | True when any sampled value was empty or null. |
| nullCount * | integer | How many sampled values were empty or null. |
| typedCandidate * | any | The narrowest non-string type that most values fit. Equal to Null when no non-string type fits. |
| One of: string | ||
| or: null | ||
| typedCandidateMismatches * | integer | How many non-empty values don't fit |
| sampledRows * | integer | How many rows the proposal was inferred from. |
| sample * | object[] | The first rows of the file as parsed, at most 50. |
| or: object | ||
| 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 Empty when nothing was written. |
| bytes * | integer | Request body size. |
| bytesWritten | integer | Present when anything was written. |
| provenance | object | The stored original, when the provenance store is available. |
| uploadId * | string | The stored original's id ( |
| filename * | string | The file name stored with it: the uploaded file's name, or |
| byteSize * | integer | The original file's size in bytes. |
| 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 | |
| projectId | string | |
| warnings | object[] | |
| code * | string | |
| message * | string | |
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.analytics.upload('<datasetSlug>')Showing example in TypeScript
{
"file": "string",
"manifest": "string"
}{
"data": {
"dryRun": true,
"detected": {
"encoding": "utf-8",
"delimiter": ",",
"format": "csv"
},
"columns": [
{
"sourceName": "string",
"name": "string",
"type": "string",
"nullable": false,
"nullCount": 0,
"typedCandidate": "string",
"typedCandidateMismatches": 0
}
],
"sampledRows": 0,
"sample": []
},
"meta": {
"timing": {
"gatewayMs": 0,
"totalMs": 0
},
"context": {
"requestId": "string",
"traceId": "string",
"projectId": "string"
},
"warnings": [
{
"code": "string",
"message": "string"
}
]
}
}