> ## 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.createSlice()

> Create a dataset slice.

Freeze the selected rows and fields at one cutoff. Use `fromSlice` to reuse an existing slice's filter at a new cutoff. Split fields are always frozen. Returns a slice with status `creating`; poll until `ready` or `failed`. Uploads and blocking field operations prevent creation.

## Signature

Method signature on `client.datasets`:

```ts theme={null}
createSlice(args: {
  datasetId: string;
  name?: string;
  itemFilter?: Extract<
    Parameters<PotatoClient["datasets"]["createSlice"]>[0],
    { itemFilter?: unknown }
  >["itemFilter"];
  frozenColumns?: string[];
} | {
  datasetId: string;
  name?: string;
  fromSlice: string;
  frozenColumns?: string[];
}): Promise<DatasetSlice>;
```

## Parameters

Pass one of the argument shapes shown in the signature.

**datasetId** `string` *required*

Dataset ID with prefix `ds.`.

**name** `string`

A name to tell slices apart, for example "October eval". Defaults to Slice 1, Slice 2 and so on.

**itemFilter** `object`

Select rows at the slice cutoff. Omit to include all rows. This filter cannot use `createdBefore`, another slice, or split parts.

**Fields**

**fieldValues** `DatasetFieldValueConditions`

Field-value conditions that selected rows must satisfy; defaults to no conditions.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-slice.md) for the complete schema.

**fieldSources** `DatasetFieldSourceConditions`

Field-author conditions that selected rows must satisfy; defaults to no conditions.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-slice.md) for the complete schema.

**missingRevisionFields** `string[]`

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

**frozenColumns** `string[]`

Fields to freeze, by name or ID. Defaults to all fields. Split fields are always frozen; other fields omitted here keep their latest values. Fields, by field name or id, to freeze at the new cutoff. Defaults to the fields the source slice froze.

**Variant 1**

**item** `string` *required*

**Variant 2**

**item** `string` *required*

**fromSlice** `string`

A ready slice of this dataset to take again: the same filter and frozen fields at a new cutoff, so rows added or changed since are picked up.

## Returns

`Promise<DatasetSlice>`

**id** `string` *required*

Slice id. The same id always selects the same rows with the same frozen values.

**datasetId** `string` *required*

ID of the dataset containing this slice, with prefix `ds.`.

**name** `string` *required*

The name that tells this slice apart.

**itemFilter** `object | null` *required*

The filter the rows matched when the slice was taken; null for every row.

**Fields**

**fieldValues** `DatasetFieldValueConditions`

Field-value conditions that selected rows must satisfy; defaults to no conditions.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-slice.md) for the complete schema.

**fieldSources** `DatasetFieldSourceConditions`

Field-author conditions that selected rows must satisfy; defaults to no conditions.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-slice.md) for the complete schema.

**missingRevisionFields** `string[]`

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

**frozenFieldIds** `string[]` *required*

Fields the slice reads as they were at its cutoff. Other fields read live.

**fromSliceId** `string | null` *required*

The slice this one was taken from, if any.

**status** `"creating" | "ready" | "failed"` *required*

Only a ready slice can select rows.

**rows** `number` *required*

Rows in the slice once it is ready; 0 until then.

**error** `object | null` *required*

Why the slice failed.

**Fields**

**code** `"no_rows" | "cutoff_not_settled"` *required*

Machine-readable reason the slice could not be created.

**message** `string` *required*

Explanation of the slice creation failure.

**cutoff** `string` *required*

The moment the slice was taken: its rows and its frozen fields are read as they were just before it.

**createdAt** `string` *required*

When the slice was requested.

## Errors

HTTP errors throw [`PotatoApiError`](https://docs.platform.toloka.ai/docs/sdk/errors). The endpoint documents these error responses:

| Status | Description |
| - | - |
| 400 | Unknown field, unsupported filter, or a source slice that is not ready |
| 404 | Dataset not found |
| 409 | An upload to the dataset is in progress, or a split field is being filled |
| 429 | Rate limit exceeded |

HTTP endpoint: [`POST /datasets/{datasetId}/slices`](https://docs.platform.toloka.ai/docs/api-reference/datasets/create-dataset-slice).

```ts createSlice() theme={null}
import { createClient } from "@toloka-platform/sdk";

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

const slice = await client.datasets.createSlice({
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  name: "Training snapshot",
  frozenColumns: [
    "text",
    "split"
  ]
});
console.log(slice);
```

```json createSlice() theme={null}
{
  "id": "dsl.019a0000-0000-7000-8000-000000000001",
  "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
  "name": "<string>",
  "itemFilter": null,
  "frozenFieldIds": [
    "df.019a0000-0000-7000-8000-000000000001"
  ],
  "fromSliceId": null,
  "status": "creating",
  "rows": 0,
  "error": null,
  "cutoff": "2026-01-01T00:00:00Z",
  "createdAt": "2026-01-01T00:00:00Z"
}
```


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