client.datasets.startUpload()

import { createClient } from "@toloka-platform/sdk";

const client = createClient({
  baseUrl: "https://platform.toloka.ai",
  apiKey: process.env.TOLOKA_API_KEY!,
});

const data = JSON.stringify([{ text: "Classify this sentence." }]);

const upload = await client.datasets.startUpload({
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  filename: "examples.json",
  format: "json",
  declaredSizeBytes: new TextEncoder().encode(data).byteLength
});
console.log(upload);

{
  "job": {
    "id": "dfu.019a0000-0000-7000-8000-000000000001",
    "status": "pending",
    "createdAt": "2026-01-01T00:00:00Z",
    "error": null,
    "result": {
      "itemsIngested": 0
    }
  },
  "uploadUrl": "<string>"
}

import { createClient } from "@toloka-platform/sdk";

const client = createClient({
  baseUrl: "https://platform.toloka.ai",
  apiKey: process.env.TOLOKA_API_KEY!,
});

const data = JSON.stringify([{ text: "Classify this sentence." }]);

const upload = await client.datasets.startUpload({
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  filename: "examples.json",
  format: "json",
  declaredSizeBytes: new TextEncoder().encode(data).byteLength
});
console.log(upload);

{
  "job": {
    "id": "dfu.019a0000-0000-7000-8000-000000000001",
    "status": "pending",
    "createdAt": "2026-01-01T00:00:00Z",
    "error": null,
    "result": {
      "itemsIngested": 0
    }
  },
  "uploadUrl": "<string>"
}

Send filename, declaredSizeBytes, and an optional format and field mapping. Files may be up to 1 GiB. Returns an upload and uploadUrl. PUT the file bytes to that URL with the required x-ms-blob-type: BlockBlob header. After the PUT succeeds, finalize the upload. The file must not exceed its declared size.

Signature

Method signature on client.datasets:

startUpload(args: {
  datasetId: string;
  filename: string;
  format?: "json" | "csv" | "jsonl";
  declaredSizeBytes: number;
  fields?: { name: string; jsonSchema?: undefined | JsonSchema }[];
}): Promise<{ job: UploadJob; uploadUrl: string }>;

Parameters

string

required

Dataset ID with prefix ds..

string

required

Name of the file being uploaded.

"json" | "csv" | "jsonl"

default:"json"

File format: “json” (a JSON array of row objects), “jsonl” (one JSON object per line) or “csv” (a header row naming the fields, one row per item; all values are ingested as strings). Defaults to “json”.

number

required

Declared maximum upload size in bytes, from 1 byte to 1 GiB.

{ name: string; jsonSchema?: undefined | JsonSchema }[]

Additional fields to create from matching keys in uploaded rows. Each complete row is also stored in “uploaded”; existing profile mappings still apply.

Show Fields

string

required

Name of a dataset field to match to a key in each row.

JsonSchema

JSON Schema for the field values. Defaults to {} (accepts any value).See the HTTP endpoint for the supported JSON Schema fields.

Returns

Promise<{ job: UploadJob; uploadUrl: string }>

UploadJob

required

A dataset upload and its import status. After finalizing, poll until status is succeeded or failed.

Show Fields

UploadId

required

Dataset upload ID with prefix dfu..

"pending" | "running" | "succeeded" | "failed"

required

Upload state: pending before finalization, running while rows are imported, succeeded when complete, or failed after failure or cancellation.

string

required

Time the upload was started, as an ISO 8601 timestamp.

string | null

required

Failure or cancellation message, or null when no error is recorded.

object

required

Progress of the dataset import.

Show Fields

number

required

Number of rows imported so far, including rows imported before a partial failure.

string

required

Signed URL for uploading file bytes with a PUT request and the x-ms-blob-type: BlockBlob header.

Errors

HTTP errors throw PotatoApiError. The endpoint documents these error responses:

Status	Description
404	Dataset not found
409	Another upload is in progress
429	Rate limit exceeded

HTTP endpoint: POST /datasets/{datasetId}/uploads.

import { createClient } from "@toloka-platform/sdk";

const client = createClient({
  baseUrl: "https://platform.toloka.ai",
  apiKey: process.env.TOLOKA_API_KEY!,
});

const data = JSON.stringify([{ text: "Classify this sentence." }]);

const upload = await client.datasets.startUpload({
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  filename: "examples.json",
  format: "json",
  declaredSizeBytes: new TextEncoder().encode(data).byteLength
});
console.log(upload);

{
  "job": {
    "id": "dfu.019a0000-0000-7000-8000-000000000001",
    "status": "pending",
    "createdAt": "2026-01-01T00:00:00Z",
    "error": null,
    "result": {
      "itemsIngested": 0
    }
  },
  "uploadUrl": "<string>"
}

Reference

TypeScript SDK

CLI

HTTP API

client.datasets.startUpload()

Signature

Parameters

Returns

Errors