> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.toloka.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# client.datasets.startUpload()

> Start a dataset file upload.

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`:

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

## Parameters

**datasetId** `string` *required*

Dataset ID with prefix `ds.`.

**filename** `string` *required*

Name of the file being uploaded.

**format** `"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".

**declaredSizeBytes** `number` *required*

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

**fields** `\{ 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.

**Fields**

**name** `string` *required*

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

**jsonSchema** `JsonSchema`

JSON Schema for the field values. Defaults to \{} (accepts any value).

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/dataset-uploads/create-dataset-upload.md) for the supported JSON Schema fields.

## Returns

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

**job** `UploadJob` *required*

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

**Fields**

**id** `UploadId` *required*

Dataset upload ID with prefix `dfu.`.

**status** `"pending" | "running" | "succeeded" | "failed"` *required*

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

**createdAt** `string` *required*

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

**error** `string | null` *required*

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

**result** `object` *required*

Progress of the dataset import.

**Fields**

**itemsIngested** `number` *required*

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

**uploadUrl** `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`](https://docs.platform.toloka.ai/docs/sdk/errors). 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`](https://docs.platform.toloka.ai/docs/api-reference/dataset-uploads/create-dataset-upload).

```ts startUpload() theme={null}
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);
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.