client.trainings.createRun()

import assert from "node:assert/strict";
import { createClient } from "@toloka-platform/sdk";

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

const estimate = await client.trainings.estimateCost({
  trainingId: "trg.019a0000-0000-7000-8000-000000000001",
  inputSetId: "tei.019a0000-0000-7000-8000-000000000001",
});
assert(estimate.status === "ready", "Resolve the estimate issues before starting a run.");

const run = await client.trainings.createRun({
  trainingId: estimate.trainingId,
  idempotencyKey: crypto.randomUUID(),
  versionName: "Text classifier v1",
  inputSetId: estimate.inputSetId,
  estimateFingerprint: estimate.fingerprint
});
console.log(run);

{
  "id": "trn.019a0000-0000-7000-8000-000000000001",
  "trainingId": "trg.019a0000-0000-7000-8000-000000000001",
  "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"
        ]
      }
    }
  },
  "estimateInputSetId": "tei.019a0000-0000-7000-8000-000000000001",
  "estimateFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "outputModelVersionId": "mdv.019a0000-0000-7000-8000-000000000001",
  "outputModelVersionName": "<string>",
  "maxCost": "<string>",
  "status": "queued",
  "outputModelVersionRevision": null,
  "progress": null,
  "blockedReason": null,
  "error": null,
  "billingStatus": "pending",
  "chargedAmount": null,
  "message": null,
  "quote": {
    "inputSetId": "tei.019a0000-0000-7000-8000-000000000001",
    "cutoff": "2026-01-01T00:00:00Z",
    "inputs": {
      "training": {
        "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
        "datasetExportId": "dex.019a0000-0000-7000-8000-000000000001",
        "report": null,
        "failure": null
      },
      "validation": null
    },
    "capabilityVersion": "<string>",
    "pricingVersion": "<string>",
    "calculatedAt": "2026-01-01T00:00:00Z",
    "budget": {
      "methodWorkUnits": 0,
      "estimatedGpuSeconds": 0,
      "estimatedWallSeconds": 0,
      "maximumWallSeconds": 0,
      "maximumGpuSeconds": 0,
      "gpuCount": 1
    },
    "maximumCharge": "<string>",
    "currency": "USD"
  },
  "inputCutoff": "2026-01-01T00:00:00Z",
  "inputs": null,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}

import assert from "node:assert/strict";
import { createClient } from "@toloka-platform/sdk";

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

const estimate = await client.trainings.estimateCost({
  trainingId: "trg.019a0000-0000-7000-8000-000000000001",
  inputSetId: "tei.019a0000-0000-7000-8000-000000000001",
});
assert(estimate.status === "ready", "Resolve the estimate issues before starting a run.");

const run = await client.trainings.createRun({
  trainingId: estimate.trainingId,
  idempotencyKey: crypto.randomUUID(),
  versionName: "Text classifier v1",
  inputSetId: estimate.inputSetId,
  estimateFingerprint: estimate.fingerprint
});
console.log(run);

{
  "id": "trn.019a0000-0000-7000-8000-000000000001",
  "trainingId": "trg.019a0000-0000-7000-8000-000000000001",
  "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"
        ]
      }
    }
  },
  "estimateInputSetId": "tei.019a0000-0000-7000-8000-000000000001",
  "estimateFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "outputModelVersionId": "mdv.019a0000-0000-7000-8000-000000000001",
  "outputModelVersionName": "<string>",
  "maxCost": "<string>",
  "status": "queued",
  "outputModelVersionRevision": null,
  "progress": null,
  "blockedReason": null,
  "error": null,
  "billingStatus": "pending",
  "chargedAmount": null,
  "message": null,
  "quote": {
    "inputSetId": "tei.019a0000-0000-7000-8000-000000000001",
    "cutoff": "2026-01-01T00:00:00Z",
    "inputs": {
      "training": {
        "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
        "datasetExportId": "dex.019a0000-0000-7000-8000-000000000001",
        "report": null,
        "failure": null
      },
      "validation": null
    },
    "capabilityVersion": "<string>",
    "pricingVersion": "<string>",
    "calculatedAt": "2026-01-01T00:00:00Z",
    "budget": {
      "methodWorkUnits": 0,
      "estimatedGpuSeconds": 0,
      "estimatedWallSeconds": 0,
      "maximumWallSeconds": 0,
      "maximumGpuSeconds": 0,
      "gpuCount": 1
    },
    "maximumCharge": "<string>",
    "currency": "USD"
  },
  "inputCutoff": "2026-01-01T00:00:00Z",
  "inputs": null,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}

Send inputSetId, estimateFingerprint, versionName, and an Idempotency-Key header. The platform checks the estimate again and returns the training run. Returns 409 if the estimate changed, the input set is in use, the version name exists, or the key was used for different input.

Signature

Method signature on client.trainings:

createRun(args: {
  trainingId: string;
  idempotencyKey: string;
  inputSetId: string;
  estimateFingerprint: string;
  versionName: string;
}): Promise<TrainingRun>;

Parameters

string

required

Training draft ID with prefix trg..

string

required

A caller-generated key reused for retries of one logical request.

string

required

Prepared input set ID with prefix tei. used for the accepted estimate.

string

required

Fingerprint from a ready cost estimate, as 64 lowercase hexadecimal characters.

string

required

Name to reserve for the output model version.

Returns

Promise<TrainingRun> The configuration, inputs, and current state of one training run.

TrainingRunId

required

ID of the training run, with prefix trn..

TrainingId

required

Training draft ID with prefix trg..

TrainingConfiguration

required

A normalized method-specific Training draft.

Show method: "sft"

"sft"

required

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

TrainingModelSource

required

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

Show type: "base_model"

"base_model"

required

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

"qwen3-4b" | "qwen3-8b" | "qwen3-32b" | "qwen3-235b"

required

Catalog base model identifier.

Show type: "model_version"

"model_version"

required

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

string

required

Source model version ID with prefix mdv..

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.

string

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

string[]

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

8 | 16 | 32

required

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

number

required

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

number

required

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

8 | 16 | 32 | 64

required

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

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.

TrainingDatasetSelection

required

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

Show Fields

string

required

Dataset ID with prefix ds. containing the selected examples.

TrainingDatasetItemFilter

required

Conditions selecting dataset rows; omitted conditions do not restrict the selection.See the HTTP endpoint for the complete schema.

TrainingDatasetSelection

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

Show Fields

string

required

Dataset ID with prefix ds. containing the selected examples.

TrainingDatasetItemFilter

required

Conditions selecting dataset rows; omitted conditions do not restrict the selection.See the HTTP endpoint for the complete schema.

Show method: "gisting"

"gisting"

required

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

TrainingModelSource

required

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

Show type: "base_model"

"base_model"

required

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

"qwen3-4b" | "qwen3-8b" | "qwen3-32b" | "qwen3-235b"

required

Catalog base model identifier.

Show type: "model_version"

"model_version"

required

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

string

required

Source model version ID with prefix mdv..

string

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

string[]

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

string

required

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

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”.

number

required

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

number

required

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

8 | 16 | 32 | 64

required

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

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.

TrainingDatasetSelection

required

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

Show Fields

string

required

Dataset ID with prefix ds. containing the selected examples.

TrainingDatasetItemFilter

required

Conditions selecting dataset rows; omitted conditions do not restrict the selection.See the HTTP endpoint for the complete schema.

TrainingDatasetSelection

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

Show Fields

string

required

Dataset ID with prefix ds. containing the selected examples.

TrainingDatasetItemFilter

required

Conditions selecting dataset rows; omitted conditions do not restrict the selection.See the HTTP endpoint for the complete schema.

TrainingCostEstimateInputSetId

required

The immutable input set used to calculate a Training Cost Estimate.

string

required

SHA-256 fingerprint of the accepted estimate, as 64 lowercase hexadecimal characters.

ModelVersionId

required

Model version ID with prefix mdv..

string

required

Name reserved for the model version this run produces.

string

required

Maximum accepted charge for this run, in US dollars as a decimal string.

required

Run state: queued, running, stopping, blocked, completed, failed, or canceled; blocked requires resolving the reported reason.

number | null

required

Published model version revision, or null before publication.

object | null

required

Latest training progress while running or stopping; null in other states or when progress is unavailable.

Show Fields

string

required

Current phase of training.

number | null

required

Current training step, or null when step progress is unavailable.

number | null

required

Total number of training steps, or null when unknown.

string | null

required

Progress explanation, or null when none is available.

"funds" | "payment" | "billing_review" | null

required

Reason the run is blocked: funds to reserve the budget, payment to settle usage, or billing_review for staff review; otherwise null.

object | null

required

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

Show Fields

required

Machine-readable reason the run failed or was canceled.

string

required

Explanation of the failure or cancellation.

boolean

required

Whether this failure is marked as retryable.

required

Billing state: pending before reservation, reserved while funds are held, release_pending or released for returned funds, settled after charging, payment_required for a shortfall, resolved after staff review, or reconciliation_required when charges need review.

string | null

required

Settled charge in US dollars as a decimal string, or null before a charge is recorded.

string | null

required

Current status or billing explanation, or null when none is available.

object

required

Cost estimate accepted for this run.

Show Fields

TrainingCostEstimateInputSetId

required

The immutable input set used to calculate a Training Cost Estimate.

string

required

Dataset cutoff used to select the inputs, as an ISO 8601 timestamp.

TrainingCostEstimateInputs

required

Prepared inputs and their validation reports.

Show Fields

object

required

Frozen training selection and its validation result.See the HTTP endpoint for the complete schema.

object | null

required

Frozen validation selection and its validation result, or null when no validation input is selected.See the HTTP endpoint for the complete schema.

string

required

Version of the model capability rules used for this estimate.

string

required

Version of the pricing rules used for this estimate.

string

required

Time the estimate was calculated, as an ISO 8601 timestamp.

TrainingResourceBudget

required

Estimated and maximum training resource usage.

Show Fields

number

required

Token-based work estimate, including epochs and the method-specific training and validation workload.

number

required

Estimated total GPU time, in seconds summed across all GPUs.

number

required

Estimated elapsed training time, in seconds.

number

required

Conservative maximum elapsed training time, in seconds.

number

required

Maximum GPU time used to bound the charge, in seconds summed across all GPUs.

number

required

Number of GPUs used for the estimate.

string

required

Maximum charge in US dollars as a decimal string.

"USD"

required

Currency used for the estimate; always USD.

string

required

Cutoff used to freeze the input rows, as an ISO 8601 timestamp.

object | null

required

Prepared training and validation inputs; null when unavailable or omitted from create and list responses.

Show Fields

object

required

Prepared files and validation report for the training input.

Show Fields

string

required

Dataset ID with prefix ds. containing these examples.

string

required

Export ID with prefix dex. that prepared these examples.

string

required

Prepared dataset file ID with prefix dfl..

TrainingInputItemFilter

required

Filter used to select this frozen training or validation input.See the HTTP endpoint for the complete schema.

"training-jsonl"

required

File format; training-jsonl stores one training example per JSON line.

"openai-chat-v1"

required

Versioned format contract for the training examples.

number

required

Size of the prepared input file in bytes.

string

required

SHA-256 checksum of the input file, as 64 lowercase hexadecimal characters.

TrainingInputReport

required

Validation results and token counts for the prepared examples.See the HTTP endpoint for the complete schema.

object | null

required

Prepared validation input, or null when no validation input was selected.

Show Fields

string

required

Dataset ID with prefix ds. containing these examples.

string

required

Export ID with prefix dex. that prepared these examples.

string

required

Prepared dataset file ID with prefix dfl..

TrainingInputItemFilter

required

Filter used to select this frozen training or validation input.See the HTTP endpoint for the complete schema.

"training-jsonl"

required

File format; training-jsonl stores one training example per JSON line.

"openai-chat-v1"

required

Versioned format contract for the training examples.

number

required

Size of the prepared input file in bytes.

string

required

SHA-256 checksum of the input file, as 64 lowercase hexadecimal characters.

TrainingInputReport

required

Validation results and token counts for the prepared examples.See the HTTP endpoint for the complete schema.

string

required

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

string

required

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

Errors

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

Status	Description
409	Changed estimate, input set already in use, duplicate version name, or idempotency key reused for different input
429	Rate limit exceeded

HTTP endpoint: POST /trainings/{trainingId}/runs.

import assert from "node:assert/strict";
import { createClient } from "@toloka-platform/sdk";

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

const estimate = await client.trainings.estimateCost({
  trainingId: "trg.019a0000-0000-7000-8000-000000000001",
  inputSetId: "tei.019a0000-0000-7000-8000-000000000001",
});
assert(estimate.status === "ready", "Resolve the estimate issues before starting a run.");

const run = await client.trainings.createRun({
  trainingId: estimate.trainingId,
  idempotencyKey: crypto.randomUUID(),
  versionName: "Text classifier v1",
  inputSetId: estimate.inputSetId,
  estimateFingerprint: estimate.fingerprint
});
console.log(run);

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

{
  "id": "trn.019a0000-0000-7000-8000-000000000001",
  "trainingId": "trg.019a0000-0000-7000-8000-000000000001",
  "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"
        ]
      }
    }
  },
  "estimateInputSetId": "tei.019a0000-0000-7000-8000-000000000001",
  "estimateFingerprint": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "outputModelVersionId": "mdv.019a0000-0000-7000-8000-000000000001",
  "outputModelVersionName": "<string>",
  "maxCost": "<string>",
  "status": "queued",
  "outputModelVersionRevision": null,
  "progress": null,
  "blockedReason": null,
  "error": null,
  "billingStatus": "pending",
  "chargedAmount": null,
  "message": null,
  "quote": {
    "inputSetId": "tei.019a0000-0000-7000-8000-000000000001",
    "cutoff": "2026-01-01T00:00:00Z",
    "inputs": {
      "training": {
        "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
        "datasetExportId": "dex.019a0000-0000-7000-8000-000000000001",
        "report": null,
        "failure": null
      },
      "validation": null
    },
    "capabilityVersion": "<string>",
    "pricingVersion": "<string>",
    "calculatedAt": "2026-01-01T00:00:00Z",
    "budget": {
      "methodWorkUnits": 0,
      "estimatedGpuSeconds": 0,
      "estimatedWallSeconds": 0,
      "maximumWallSeconds": 0,
      "maximumGpuSeconds": 0,
      "gpuCount": 1
    },
    "maximumCharge": "<string>",
    "currency": "USD"
  },
  "inputCutoff": "2026-01-01T00:00:00Z",
  "inputs": null,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}

Reference

TypeScript SDK

CLI

HTTP API

client.trainings.createRun()

Signature

Parameters

Returns

Errors

​Signature

​Parameters

​Returns

​Errors

Signature

Parameters

Returns

Errors