client.datasets.split()

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

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

const field = await client.datasets.split({
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  column: "split",
  parts: [
    {
      name: "train",
      roles: [
        "train"
      ],
      share: 0.8
    },
    {
      name: "validation",
      roles: [
        "validate"
      ],
      share: 0.1
    },
    {
      name: "test",
      roles: [
        "test"
      ],
      share: 0.1
    }
  ],
  seed: 42
});
console.log(field);

{
  "id": "df.019a0000-0000-7000-8000-000000000001",
  "name": "<string>",
  "description": null,
  "jsonSchema": {},
  "internal": false,
  "split": null,
  "operations": [
    {
      "type": "copy",
      "sourceFieldId": "df.019a0000-0000-7000-8000-000000000001",
      "blocking": false
    }
  ],
  "createdAt": "2026-01-01T00:00:00Z"
}

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

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

const field = await client.datasets.split({
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  column: "split",
  parts: [
    {
      name: "train",
      roles: [
        "train"
      ],
      share: 0.8
    },
    {
      name: "validation",
      roles: [
        "validate"
      ],
      share: 0.1
    },
    {
      name: "test",
      roles: [
        "test"
      ],
      share: 0.1
    }
  ],
  seed: 42
});
console.log(field);

{
  "id": "df.019a0000-0000-7000-8000-000000000001",
  "name": "<string>",
  "description": null,
  "jsonSchema": {},
  "internal": false,
  "split": null,
  "operations": [
    {
      "type": "copy",
      "sourceFieldId": "df.019a0000-0000-7000-8000-000000000001",
      "blocking": false
    }
  ],
  "createdAt": "2026-01-01T00:00:00Z"
}

Send an optional split field name in column, parts, and row selection. Assigns unassigned rows to named parts while keeping existing assignments. Returns the split field; poll its split status until ready or failed. To train on the result, create a slice that freezes this field.

Signature

Method signature on client.datasets:

split(args: {
  datasetId: string;
  column?: string;
  parts?: { name: string; roles: ("train" | "validate" | "test")[]; share?: undefined | number }[];
  balanceBy?: string;
  seed?: number;
  slice?: string;
  itemFilter?: Parameters<PotatoClient["datasets"]["split"]>[0]["itemFilter"];
}): Promise<DatasetField>;

Parameters

string

required

Dataset ID with prefix ds..

string

default:"split"

The name of the split field. Defaults to “split”. A new name creates a field; an existing split field fills unassigned rows using its saved parts and shares. An ordinary field can be adopted if its values are part names.

{ name: string; roles: ("train" | "validate" | "test")[]; share?: undefined | number }[]

Parts with names, roles, and optional shares. Shares must total 1. New split fields default to train 0.8, validate 0.1, and test 0.1; existing split fields reuse their parts and shares. A train role cannot be combined with another role. A part may have both validate and test roles, or no roles. Omit all shares to adopt existing part values without assigning rows; adoption does not accept seed, balanceBy, slice, or itemFilter.

Show Fields

string

required

Name stored in the split field for rows assigned to this part.

("train" | "validate" | "test")[]

required

Training uses train parts, evaluates on validate parts, and excludes test parts from training; an empty array assigns no role.See the HTTP endpoint for the complete schema.

Target fraction of rows in this part, greater than 0 and at most 1; omit all shares to adopt existing assignments.

string

Field name or ID to balance by. Rows with each label value are distributed across parts to preserve the label mix. Rare labels may be absent from some parts.

number

Seed for repeatable assignments. The same seed and row order produce the same assignments, including across datasets. Generated when omitted and saved with the split field.

string

Assign only unassigned rows in this slice. Processing waits for a slice that is still being created. Omit both slice and itemFilter to include all unassigned rows.

object

Assign only unassigned rows matching this filter when processing starts.

Show Fields

DatasetFieldValueConditions

Field-value conditions that selected rows must satisfy; defaults to no conditions.See the HTTP endpoint for the complete schema.

DatasetFieldSourceConditions

Field-author conditions that selected rows must satisfy; defaults to no conditions.See the HTTP endpoint for the complete schema.

string[]

Field IDs with prefix df. that must have no revision on a selected row; defaults to an empty array.

Returns

Promise<DatasetField> A field of a dataset.

DatasetFieldId

required

Dataset field ID with prefix df..

string

required

Name of the dataset field.

string | null

required

Description of the field, or null when none is set.

JsonSchema

required

JSON Schema that values in this field must satisfy.See the HTTP endpoint for the supported JSON Schema fields.

boolean

required

True when this field is excluded from pipeline input bindings. The field is still included in dataset field responses.

object | null

required

Set when this is a split field: each row’s value names its part.

Show Fields

object[]

required

The parts, with their roles: trainings learn on train parts and validate on validate parts. Test parts are held out for evaluations: no training learns on them, and only a training on this field validates on a part that has both the validate and test roles.See the HTTP endpoint for the complete schema.

object | null

required

How the next fill samples parts; null for an adopted field until a fill gives it shares.

Show Fields

object[]

required

Target proportion of rows for each split part.See the HTTP endpoint for the complete schema.

string | null

required

Field ID with prefix df. used to balance labels, or null when balancing is disabled.

number

required

Seed used to make the part assignments repeatable.

"filling" | "ready" | "failed"

required

A slice cannot be taken while the field is filling.

object | null

required

Rows placed so far while the field is filling.

Show Fields

number

required

Number of previously unassigned rows placed so far.

number

required

Number of rows to place in this fill.

object | null

required

The last fill: rows it placed, rows that already had a part, and the rows each part held after it.

Show Fields

number

required

Number of previously unassigned rows placed by the last fill.

number

required

Number of rows whose existing part assignments were kept.

object

required

Row counts for each part after the last fill, keyed by part name.

object | null

required

Why the last fill failed.

Show Fields

"too_many_labels" | "slice_failed"

required

Machine-readable reason the split fill failed.

string

required

Explanation of the split fill failure.

DatasetFieldOperation[]

required

Operations currently writing to this field. A split or slice that reads the field is rejected while a blocking operation runs.

Show type: "copy"

"copy"

required

Operation kind: copy copies field values, split_fill assigns split parts, and write writes new field revisions.

DatasetFieldId

required

The field the values are copied from.

boolean

required

True when splits and slices that read this field must wait for the operation to finish.

Show type: "split_fill"

"split_fill"

required

Operation kind: copy copies field values, split_fill assigns split parts, and write writes new field revisions.

boolean

required

True when splits and slices that read this field must wait for the operation to finish.

Show type: "write"

"write"

required

Operation kind: copy copies field values, split_fill assigns split parts, and write writes new field revisions.

string

required

The source of the new field revisions. For a batch inference run, this is batch-inference-run:<id>.

object | null

required

The number of rows written and the total number expected, when known.See the HTTP endpoint for the complete schema.

boolean

required

True when splits and slices that read this field must wait for the operation to finish.

string

required

Time the field was created, as an ISO 8601 timestamp.

Errors

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

Status	Description
400	Unknown balancing field, failed slice, or values that are not parts
404	Dataset or slice not found
409	The field is still being filled
429	Rate limit exceeded

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

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

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

const field = await client.datasets.split({
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  column: "split",
  parts: [
    {
      name: "train",
      roles: [
        "train"
      ],
      share: 0.8
    },
    {
      name: "validation",
      roles: [
        "validate"
      ],
      share: 0.1
    },
    {
      name: "test",
      roles: [
        "test"
      ],
      share: 0.1
    }
  ],
  seed: 42
});
console.log(field);

{
  "id": "df.019a0000-0000-7000-8000-000000000001",
  "name": "<string>",
  "description": null,
  "jsonSchema": {},
  "internal": false,
  "split": null,
  "operations": [
    {
      "type": "copy",
      "sourceFieldId": "df.019a0000-0000-7000-8000-000000000001",
      "blocking": false
    }
  ],
  "createdAt": "2026-01-01T00:00:00Z"
}

Reference

TypeScript SDK

CLI

HTTP API

Signature

Parameters

Returns

Errors

​Signature

​Parameters

​Returns

​Errors

Signature

Parameters

Returns

Errors