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

> Replace a training configuration.

Send the complete configuration, including a ready dataset slice that freezes a split field. Returns the updated training. Concurrent changes use the last write; archived trainings cannot be updated.

## Signature

Method signature on `client.trainings`:

```ts theme={null}
replaceConfiguration(args: {
  trainingId: string;
  configuration: TrainingConfigurationInput;
}): Promise<Training>;
```

## Parameters

**trainingId** `string` *required*

Training draft ID with prefix `trg.`.

**configuration** `TrainingConfigurationInput` *required*

Method-specific Training draft input.

**method: "sft"**

**method** `"sft"` *required*

Training method; `sft` learns a LoRA adapter from prompt and target examples.

**source** `TrainingModelSource` *required*

The exact Base Model or Model Version used as the source.

**type: "base\_model"**

**type** `"base_model"` *required*

Training source: `base_model` uses a catalog model; `model_version` uses a published project model version.

**baseModelId** `"qwen3-4b" | "qwen3-8b" | "qwen3-32b" | "qwen3-235b"` *required*

Catalog base model identifier.

**type: "model\_version"**

**type** `"model_version"` *required*

Training source: `base_model` uses a catalog model; `model_version` uses a published project model version.

**modelVersionId** `string` *required*

Source model version ID with prefix `mdv.`.

**sliceId** `string` *required*

The dataset slice to train on. It must freeze a split field. Training uses its train parts and validation uses its validate parts at the slice cutoff. Rows marked as test by any split field are excluded, except validation rows in a part with both validate and test roles in the selected split field.

**splitFieldId** `string`

The split field to use, identified by field ID. Required when the slice freezes more than one split field.

**trainParts** `string[]`

The train parts to learn on. Defaults to every part with the train role.

**loraRank** `8 | 16 | 32` (default: 16)

LoRA adapter rank: 8, 16, or 32. Defaults to 16. Alpha is twice the rank.

**epochs** `number` (default: 3)

Passes over the training selection, 1 through 5. The cost estimate grows linearly with epochs.

**learningRate** `number` (default: 0.00015)

Optimizer learning rate, 0.00001 through 0.001. The default is 0.00015.

**batchSize** `8 | 16 | 32 | 64` (default: 8)

Sequences per optimizer step across all GPUs: 8, 16, 32, or 64. The default is 8.

**maxSequenceLength** `number` (default: 12288)

Token budget per training example, prompt and target together: 64 through 16384. The cost estimate is blocked when the longest example exceeds it. Defaults: 12288 for SFT, 3072 for gisting.

**method: "gisting"**

**method** `"gisting"` *required*

Training method; `gisting` learns tokens that replace a reusable prompt.

**source** `TrainingModelSource` *required*

The exact Base Model or Model Version used as the source.

**type: "base\_model"**

**type** `"base_model"` *required*

Training source: `base_model` uses a catalog model; `model_version` uses a published project model version.

**baseModelId** `"qwen3-4b" | "qwen3-8b" | "qwen3-32b" | "qwen3-235b"` *required*

Catalog base model identifier.

**type: "model\_version"**

**type** `"model_version"` *required*

Training source: `base_model` uses a catalog model; `model_version` uses a published project model version.

**modelVersionId** `string` *required*

Source model version ID with prefix `mdv.`.

**sliceId** `string` *required*

The dataset slice to train on. It must freeze a split field. Training uses its train parts and validation uses its validate parts at the slice cutoff. Rows marked as test by any split field are excluded, except validation rows in a part with both validate and test roles in the selected split field.

**splitFieldId** `string`

The split field to use, identified by field ID. Required when the slice freezes more than one split field.

**trainParts** `string[]`

The train parts to learn on. Defaults to every part with the train role.

**promptFileId** `string` *required*

Project file ID with prefix `ppf.` containing the finalized UTF-8 prompt to compress.

**gistTokens** `8 | 32 | 64 | "1/4" | "1/8" | "1/16" | "1/32"` (default: 1/8)

Number of learned tokens that replace the prompt: 8, 32, 64, or a fraction of the prompt length: "1/4", "1/8", "1/16", or "1/32". Fractions are rounded up to a whole token and limited to 8 through 256 tokens. Defaults to "1/8".

**epochs** `number` (default: 3)

Passes over the training selection, 1 through 5. The cost estimate grows linearly with epochs.

**learningRate** `number` (default: 0.03)

Optimizer learning rate for the soft tokens, 0.001 through 0.3. The default is 0.03.

**batchSize** `8 | 16 | 32 | 64` (default: 8)

Sequences per optimizer step across all GPUs: 8, 16, 32, or 64. The default is 8.

**maxSequenceLength** `number` (default: 3072)

Token budget per training example, prompt and target together: 64 through 16384. The cost estimate is blocked when the longest example exceeds it. Defaults: 12288 for SFT, 3072 for gisting.

## Returns

`Promise<Training>`

A project-owned mutable Training draft. The output Model is bound on the first Training Run.

**id** `TrainingId` *required*

Training draft ID with prefix `trg.`.

**projectId** `ProjectId` *required*

Project ID with prefix `pp.`.

**modelId** `ModelId | null` *required*

Output model ID with prefix `mdl.`, or null before the first training run.

**name** `string` *required*

Name of the training draft.

**configuration** `TrainingConfiguration` *required*

A normalized method-specific Training draft.

**method: "sft"**

**method** `"sft"` *required*

Training method; `sft` learns a LoRA adapter from prompt and target examples.

**source** `TrainingModelSource` *required*

The exact Base Model or Model Version used as the source.

**type: "base\_model"**

**type** `"base_model"` *required*

Training source: `base_model` uses a catalog model; `model_version` uses a published project model version.

**baseModelId** `"qwen3-4b" | "qwen3-8b" | "qwen3-32b" | "qwen3-235b"` *required*

Catalog base model identifier.

**type: "model\_version"**

**type** `"model_version"` *required*

Training source: `base_model` uses a catalog model; `model_version` uses a published project model version.

**modelVersionId** `string` *required*

Source model version ID with prefix `mdv.`.

**sliceId** `string`

The dataset slice to train on. It must freeze a split field. Training uses its train parts and validation uses its validate parts at the slice cutoff. Rows marked as test by any split field are excluded, except validation rows in a part with both validate and test roles in the selected split field.

**splitFieldId** `string`

The split field to use, identified by field ID. Required when the slice freezes more than one split field.

**trainParts** `string[]`

The train parts to learn on. Defaults to every part with the train role.

**loraRank** `8 | 16 | 32` *required*

LoRA adapter rank: 8, 16, or 32. Defaults to 16. Alpha is twice the rank.

**epochs** `number` *required*

Passes over the training selection, 1 through 5. The cost estimate grows linearly with epochs.

**learningRate** `number` *required*

Optimizer learning rate, 0.00001 through 0.001. The default is 0.00015.

**batchSize** `8 | 16 | 32 | 64` *required*

Sequences per optimizer step across all GPUs: 8, 16, 32, or 64. The default is 8.

**maxSequenceLength** `number` *required*

Token budget per training example, prompt and target together: 64 through 16384. The cost estimate is blocked when the longest example exceeds it. Defaults: 12288 for SFT, 3072 for gisting.

**training** `TrainingDatasetSelection` *required*

A Dataset and normalized filter selected for one Training input purpose.

**Fields**

**datasetId** `string` *required*

Dataset ID with prefix `ds.` containing the selected examples.

**itemFilter** `TrainingDatasetItemFilter` *required*

Conditions selecting dataset rows; omitted conditions do not restrict the selection.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/trainings/replace-training-configuration.md) for the complete schema.

**validation** `TrainingDatasetSelection`

A Dataset and normalized filter selected for one Training input purpose.

**Fields**

**datasetId** `string` *required*

Dataset ID with prefix `ds.` containing the selected examples.

**itemFilter** `TrainingDatasetItemFilter` *required*

Conditions selecting dataset rows; omitted conditions do not restrict the selection.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/trainings/replace-training-configuration.md) for the complete schema.

**method: "gisting"**

**method** `"gisting"` *required*

Training method; `gisting` learns tokens that replace a reusable prompt.

**source** `TrainingModelSource` *required*

The exact Base Model or Model Version used as the source.

**type: "base\_model"**

**type** `"base_model"` *required*

Training source: `base_model` uses a catalog model; `model_version` uses a published project model version.

**baseModelId** `"qwen3-4b" | "qwen3-8b" | "qwen3-32b" | "qwen3-235b"` *required*

Catalog base model identifier.

**type: "model\_version"**

**type** `"model_version"` *required*

Training source: `base_model` uses a catalog model; `model_version` uses a published project model version.

**modelVersionId** `string` *required*

Source model version ID with prefix `mdv.`.

**sliceId** `string`

The dataset slice to train on. It must freeze a split field. Training uses its train parts and validation uses its validate parts at the slice cutoff. Rows marked as test by any split field are excluded, except validation rows in a part with both validate and test roles in the selected split field.

**splitFieldId** `string`

The split field to use, identified by field ID. Required when the slice freezes more than one split field.

**trainParts** `string[]`

The train parts to learn on. Defaults to every part with the train role.

**promptFileId** `string` *required*

Project file ID with prefix `ppf.` containing the finalized UTF-8 prompt to compress.

**gistTokens** `8 | 32 | 64 | "1/4" | "1/8" | "1/16" | "1/32"` *required*

Number of learned tokens that replace the prompt: 8, 32, 64, or a fraction of the prompt length: "1/4", "1/8", "1/16", or "1/32". Fractions are rounded up to a whole token and limited to 8 through 256 tokens. Defaults to "1/8".

**epochs** `number` *required*

Passes over the training selection, 1 through 5. The cost estimate grows linearly with epochs.

**learningRate** `number` *required*

Optimizer learning rate for the soft tokens, 0.001 through 0.3. The default is 0.03.

**batchSize** `8 | 16 | 32 | 64` *required*

Sequences per optimizer step across all GPUs: 8, 16, 32, or 64. The default is 8.

**maxSequenceLength** `number` *required*

Token budget per training example, prompt and target together: 64 through 16384. The cost estimate is blocked when the longest example exceeds it. Defaults: 12288 for SFT, 3072 for gisting.

**training** `TrainingDatasetSelection` *required*

A Dataset and normalized filter selected for one Training input purpose.

**Fields**

**datasetId** `string` *required*

Dataset ID with prefix `ds.` containing the selected examples.

**itemFilter** `TrainingDatasetItemFilter` *required*

Conditions selecting dataset rows; omitted conditions do not restrict the selection.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/trainings/replace-training-configuration.md) for the complete schema.

**validation** `TrainingDatasetSelection`

A Dataset and normalized filter selected for one Training input purpose.

**Fields**

**datasetId** `string` *required*

Dataset ID with prefix `ds.` containing the selected examples.

**itemFilter** `TrainingDatasetItemFilter` *required*

Conditions selecting dataset rows; omitted conditions do not restrict the selection.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/trainings/replace-training-configuration.md) for the complete schema.

**archivedAt** `string | null` *required*

Time the training was archived, as an ISO 8601 timestamp, or null while it is active.

**createdAt** `string` *required*

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

**updatedAt** `string` *required*

Time the training was last updated, as an ISO 8601 timestamp.

## Errors

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

| Status | Description |
| - | - |
| 404 | Training, Dataset, Dataset Slice, Model Version, or gisting prompt file not found |
| 409 | Archived Training cannot be updated |
| 429 | Rate limit exceeded |

HTTP endpoint: [`PUT /trainings/{trainingId}/configuration`](https://docs.platform.toloka.ai/docs/api-reference/trainings/replace-training-configuration).

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

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

const training = await client.trainings.replaceConfiguration({
  trainingId: "trg.019a0000-0000-7000-8000-000000000001",
  configuration: {
    method: "sft",
    source: {
      type: "base_model",
      baseModelId: "qwen3-4b"
    },
    sliceId: "dsl.019a0000-0000-7000-8000-000000000001"
  }
});
console.log(training);
```

Nested values in this example are abbreviated. The HTTP endpoint has the complete schema.

```json replaceConfiguration() theme={null}
{
  "id": "trg.019a0000-0000-7000-8000-000000000001",
  "projectId": "pp.019a0000-0000-7000-8000-000000000001",
  "modelId": null,
  "name": "<string>",
  "configuration": {
    "method": "sft",
    "source": {
      "type": "base_model",
      "baseModelId": "qwen3-4b"
    },
    "loraRank": 8,
    "epochs": 1,
    "learningRate": 0.00001,
    "batchSize": 8,
    "maxSequenceLength": 64,
    "training": {
      "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
      "itemFilter": {
        "fieldValues": [
          {}
        ],
        "fieldSources": [
          {}
        ],
        "missingRevisionFields": [
          "df.019a0000-0000-7000-8000-000000000001"
        ]
      }
    }
  },
  "archivedAt": null,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```


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