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

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

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
file *string <binary>

The CSV or JSON file (?format=csv|json), at most 25 MiB.

manifeststring

JSON: creates the dataset from this definition, then ingests the file.

Omit it to append to an existing dataset.

Responses
HTTPK9O CodeDescription
200Success
400K9O_INGEST_PARSE_FAILEDThe file cannot be parsed, exceeds 25 MiB, or a query parameter or the manifest is invalid.
400K9O_INGEST_SCHEMA_MISMATCHA row does not match the dataset's schema and `onError=reject`.
400K9O_DATASET_INVALIDThe manifest is invalid, or the dataset already exists.
400K9O_DATASET_STORAGE_TARGET_INVALIDThe manifest's storage location does not exist or is retired.
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.
429K9O_DATASET_LIMIT_EXCEEDEDThe project already has the maximum number of datasets (200).
503K9O_ANALYTICS_UNAVAILABLEThe region's analytics storage is not available yet; retry later.
Response body (200)
data *any

?dryRun=true: the inferred schema and a sample; otherwise the ingest result.

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 encoding you sent.

delimiter"," | ";" | "\t"

The CSV field delimiter: detected from the header line, or the delimiter you sent.

Absent for JSON.

format *"csv" | "json"

The file format, from ?format=.

columns *object[]

The proposed columns, in file order.

Review them, then create the dataset with them (or send them as the manifest).

sourceName *string

The column's name in the file: the CSV header cell, col_1, col_2, ... when hasHeader=false, or the JSON key.

name *string

The proposed column name: sourceName trimmed and lowercased, with each run of characters other than letters and digits turned into one _.

type *string

The proposed column type: the narrowest type every non-empty sampled value fits, or string.

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 type when the column fits it cleanly; when type is string because a few values don't fit, this names the type they broke.

Null when no non-string type fits.

One of: string
or: null
typedCandidateMismatches *integer

How many non-empty values don't fit typedCandidate: the rows that would be skipped if you declared it. 0 when the column fits cleanly.

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 region=eu/occurred_at=2026-11-02.

Empty when nothing was written.

bytes *integer

Request body size.

bytesWritteninteger

Present when anything was written.

provenanceobject

The stored original, when the provenance store is available.

uploadId *string

The stored original's id (prov_...).

filename *string

The file name stored with it: the uploaded file's name, or upload.csv / upload.json when it had none.

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
projectIdstring
warningsobject[]
code *string
message *string
TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.analytics.upload('<datasetSlug>')

Showing example in TypeScript

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

More in Analytics & Intelligence