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

> Get a training run.

Return run status, progress, billing details, and input selections. Poll until `completed`, `failed`, or `canceled`. If `blocked`, inspect `blockedReason` and `message`.

## Signature

Method signature on `client.trainings`:

```ts theme={null}
getRun(args: {
  trainingRunId: string;
}): Promise<TrainingRun>;
```

## Parameters

**trainingRunId** `string` *required*

ID of the training run, with prefix `trn.`.

## Returns

`Promise<TrainingRun>`

The configuration, inputs, and current state of one training run.

**id** `TrainingRunId` *required*

ID of the training run, with prefix `trn.`.

**trainingId** `TrainingId` *required*

Training draft ID with prefix `trg.`.

**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/get-training-run.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/get-training-run.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/get-training-run.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/get-training-run.md) for the complete schema.

**estimateInputSetId** `TrainingCostEstimateInputSetId` *required*

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

**estimateFingerprint** `string` *required*

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

**outputModelVersionId** `ModelVersionId` *required*

Model version ID with prefix `mdv.`.

**outputModelVersionName** `string` *required*

Name reserved for the model version this run produces.

**maxCost** `string` *required*

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

**status** `"queued" | "running" | "stopping" | "blocked" | "completed" | "failed" | "canceled"` *required*

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

**outputModelVersionRevision** `number | null` *required*

Published model version revision, or null before publication.

**progress** `object | null` *required*

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

**Fields**

**phase** `string` *required*

Current phase of training.

**step** `number | null` *required*

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

**total** `number | null` *required*

Total number of training steps, or null when unknown.

**message** `string | null` *required*

Progress explanation, or null when none is available.

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

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

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

**Fields**

**code** `"data_export_failed" | "input_report_mismatch" | "billing_rejected" | "provider_failed" | "provider_timeout" | "invalid_provider_output" | "provider_output_changed" | "prompt_changed" | "payment_window_expired" | "canceled"` *required*

Machine-readable reason the run failed or was canceled.

**message** `string` *required*

Explanation of the failure or cancellation.

**retryable** `boolean` *required*

Whether this failure is marked as retryable.

**billingStatus** `"pending" | "reserved" | "release_pending" | "released" | "settled" | "payment_required" | "resolved" | "reconciliation_required"` *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.

**chargedAmount** `string | null` *required*

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

**message** `string | null` *required*

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

**quote** `object` *required*

Cost estimate accepted for this run.

**Fields**

**inputSetId** `TrainingCostEstimateInputSetId` *required*

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

**cutoff** `string` *required*

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

**inputs** `TrainingCostEstimateInputs` *required*

Prepared inputs and their validation reports.

**Fields**

**training** `object` *required*

Frozen training selection and its validation result.

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

**validation** `object | null` *required*

Frozen validation selection and its validation result, or null when no validation input is selected.

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

**capabilityVersion** `string` *required*

Version of the model capability rules used for this estimate.

**pricingVersion** `string` *required*

Version of the pricing rules used for this estimate.

**calculatedAt** `string` *required*

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

**budget** `TrainingResourceBudget` *required*

Estimated and maximum training resource usage.

**Fields**

**methodWorkUnits** `number` *required*

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

**estimatedGpuSeconds** `number` *required*

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

**estimatedWallSeconds** `number` *required*

Estimated elapsed training time, in seconds.

**maximumWallSeconds** `number` *required*

Conservative maximum elapsed training time, in seconds.

**maximumGpuSeconds** `number` *required*

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

**gpuCount** `number` *required*

Number of GPUs used for the estimate.

**maximumCharge** `string` *required*

Maximum charge in US dollars as a decimal string.

**currency** `"USD"` *required*

Currency used for the estimate; always `USD`.

**inputCutoff** `string` *required*

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

**inputs** `object | null` *required*

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

**Fields**

**training** `object` *required*

Prepared files and validation report for the training input.

**Fields**

**datasetId** `string` *required*

Dataset ID with prefix `ds.` containing these examples.

**datasetExportId** `string` *required*

Export ID with prefix `dex.` that prepared these examples.

**datasetFileId** `string` *required*

Prepared dataset file ID with prefix `dfl.`.

**itemFilter** `TrainingInputItemFilter` *required*

Filter used to select this frozen training or validation input.

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

**format** `"training-jsonl"` *required*

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

**contract** `"openai-chat-v1"` *required*

Versioned format contract for the training examples.

**byteSize** `number` *required*

Size of the prepared input file in bytes.

**sha256** `string` *required*

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

**report** `TrainingInputReport` *required*

Validation results and token counts for the prepared examples.

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

**validation** `object | null` *required*

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

**Fields**

**datasetId** `string` *required*

Dataset ID with prefix `ds.` containing these examples.

**datasetExportId** `string` *required*

Export ID with prefix `dex.` that prepared these examples.

**datasetFileId** `string` *required*

Prepared dataset file ID with prefix `dfl.`.

**itemFilter** `TrainingInputItemFilter` *required*

Filter used to select this frozen training or validation input.

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

**format** `"training-jsonl"` *required*

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

**contract** `"openai-chat-v1"` *required*

Versioned format contract for the training examples.

**byteSize** `number` *required*

Size of the prepared input file in bytes.

**sha256** `string` *required*

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

**report** `TrainingInputReport` *required*

Validation results and token counts for the prepared examples.

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

**createdAt** `string` *required*

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

**updatedAt** `string` *required*

Time the training run 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 Run not found |
| 429 | Rate limit exceeded |

HTTP endpoint: [`GET /training-runs/{trainingRunId}`](https://docs.platform.toloka.ai/docs/api-reference/trainings/get-training-run).

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

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

const run = await client.trainings.getRun({
  trainingRunId: "trn.019a0000-0000-7000-8000-000000000001"
});
console.log(run);
```

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

```json getRun() theme={null}
{
  "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"
}
```


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