client.batchInference.createRun()

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

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

const run = await client.batchInference.createRun({
  projectId: "pp.019a0000-0000-7000-8000-000000000001",
  idempotencyKey: crypto.randomUUID(),
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  model: {
    type: "base_model",
    baseModelId: "qwen3-4b"
  },
  sampling: {
    maxOutputTokens: 256
  },
  output: {
    type: "field",
    fieldName: "answer"
  }
});
console.log(run);

{
  "id": "bir.019a0000-0000-7000-8000-000000000001",
  "projectId": "pp.019a0000-0000-7000-8000-000000000001",
  "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
  "model": {
    "type": "base_model",
    "baseModelId": "qwen3-4b"
  },
  "mode": {
    "type": "single_turn"
  },
  "sampling": {
    "maxOutputTokens": 1
  },
  "output": {
    "type": "field",
    "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
    "fieldId": "df.019a0000-0000-7000-8000-000000000001"
  },
  "status": "preparing",
  "progress": null,
  "blockedReason": null,
  "message": null,
  "error": null,
  "quote": null,
  "chargedAmount": null,
  "result": null,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "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 run = await client.batchInference.createRun({
  projectId: "pp.019a0000-0000-7000-8000-000000000001",
  idempotencyKey: crypto.randomUUID(),
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  model: {
    type: "base_model",
    baseModelId: "qwen3-4b"
  },
  sampling: {
    maxOutputTokens: 256
  },
  output: {
    type: "field",
    fieldName: "answer"
  }
});
console.log(run);

{
  "id": "bir.019a0000-0000-7000-8000-000000000001",
  "projectId": "pp.019a0000-0000-7000-8000-000000000001",
  "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
  "model": {
    "type": "base_model",
    "baseModelId": "qwen3-4b"
  },
  "mode": {
    "type": "single_turn"
  },
  "sampling": {
    "maxOutputTokens": 1
  },
  "output": {
    "type": "field",
    "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
    "fieldId": "df.019a0000-0000-7000-8000-000000000001"
  },
  "status": "preparing",
  "progress": null,
  "blockedReason": null,
  "message": null,
  "error": null,
  "quote": null,
  "chargedAmount": null,
  "result": null,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}

Send the dataset, model, sampling settings, and output destination, with an Idempotency-Key header. Returns a run that prepares a quote for frozen input rows. Confirm the quote before funds are reserved or inference starts.

Signature

Method signature on client.batchInference:

createRun(args: {
  projectId: string;
  idempotencyKey: string;
  datasetId: string;
  itemFilter?: Parameters<PotatoClient["batchInference"]["createRun"]>[0]["itemFilter"];
  model: ModelVersionParent;
  mode?: BatchInferenceMode;
  sampling: Parameters<PotatoClient["batchInference"]["createRun"]>[0]["sampling"];
  output: { type: "field"; fieldName: string } | { type: "dataset"; name: string };
}): Promise<BatchInferenceRun>;

Parameters

string

required

Project ID with prefix pp..

string

required

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

string

required

Source dataset ID with prefix ds..

object

Filter selecting rows to answer; omit to include all rows.

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.

DatasetSliceSelection

Slice whose frozen rows and fields to read; omit to use live dataset rows.

Show Fields

string

required

Dataset slice ID with prefix dsl..

DatasetSplitPartInclusion

Split parts to include; omit to include every part.

Show Fields

string

required

Split field ID with prefix df..

string[]

required

Names of the split parts to select.See the HTTP endpoint for the complete schema.

DatasetSplitPartExclusions

Split-part selections to exclude; omit when no parts should be excluded.See the HTTP endpoint for the complete schema.

ModelVersionParent

required

The model to use: a catalog base model or a model version in this project containing a LoRA adapter or full weights. More model types may be added, so branch on type.

Show type: "base_model"

"base_model"

required

Model 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

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

string

required

Model version ID with prefix mdv..

BatchInferenceMode

How each row is processed. Defaults to single_turn: one model call per row, with the answer written as text. More modes may be added, so branch on type.

Show Fields

"single_turn"

required

Processing mode; single_turn makes one model call for each requested sample of a row.

object

required

Generation settings for every model call: maxOutputTokens caps each answer and bounds the quote, and samplesPerRow is how many answers each row gets.

Show Fields

number

required

Maximum number of generated tokens per answer, from 1 to 8192.

number

default:"0"

Sampling temperature from 0 to 2; defaults to 0.

number

Cumulative probability cutoff for nucleus sampling, greater than 0 and at most 1; omit to use the model default.

string[]

One to four strings that stop generation when encountered; absent when no stop strings are set.

number

Optional sampling seed, from 0 to 2147483647.

number

default:"1"

Number of answers to generate for each row, from 1 to 16; defaults to 1.

{ type: "field"; fieldName: string } | { type: "dataset"; name: string }

required

Where completions land: a text field on the source dataset, or a new chat-sft dataset.

Show type: "field"

"field"

required

Output destination: field writes a text field in the source dataset; dataset creates a chat training dataset.

string

required

Name of the text field to receive the generated answers.

Show type: "dataset"

"dataset"

required

Output destination: field writes a text field in the source dataset; dataset creates a chat training dataset.

string

required

Name of the new dataset that will receive the generated answers.

Returns

Promise<BatchInferenceRun> A batch inference run with its quote, progress, charge, and output location.

BatchInferenceRunId

required

ID of the batch inference run, with prefix bir..

ProjectId

required

Project ID with prefix pp..

DatasetId

required

Dataset ID with prefix ds..

BatchInferenceModel

required

The model to use: a catalog base model or a model version in this project containing a LoRA adapter or full weights. More model types may be added, so branch on type.

Show type: "base_model"

"base_model"

required

Model 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

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

string

required

Model version ID with prefix mdv..

BatchInferenceMode

required

How each row is processed. Defaults to single_turn: one model call per row, with the answer written as text. More modes may be added, so branch on type.

Show Fields

"single_turn"

required

Processing mode; single_turn makes one model call for each requested sample of a row.

object

required

Generation settings used for each model call.

Show Fields

number

required

Maximum number of generated tokens per answer, from 1 to 8192.

number

default:"0"

Sampling temperature from 0 to 2; defaults to 0.

number

Cumulative probability cutoff for nucleus sampling, greater than 0 and at most 1; omit to use the model default.

string[]

One to four strings that stop generation when encountered; absent when no stop strings are set.

number

Optional sampling seed, from 0 to 2147483647.

number

default:"1"

Number of answers to generate for each row, from 1 to 16; defaults to 1.

object

required

Dataset and field where this run writes completions.

Show Fields

"field" | "dataset"

required

Output destination: field writes to the source dataset, while dataset writes to a new dataset.

DatasetId

required

Dataset ID with prefix ds..

DatasetFieldId

required

Dataset field ID with prefix df..

required

Run state from input preparation through confirmation, execution, and output writing; stopping is cancellation in progress, blocked requires action, and completed, failed, or canceled are terminal.

object | null

required

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

Show Fields

"queued" | "preparing" | "generating" | "finishing"

required

Generation phase: queued, preparing inputs, generating answers, or finishing results.

object

Request progress; absent when request counts are unavailable.

Show Fields

number

required

Number of model requests completed.

number

required

Total number of model requests.

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

string | null

required

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

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.

object | null

required

Price quote for confirmation, or null before a quote is ready.

Show Fields

number

required

Number of model requests included in the quote.

number

required

Number of selected rows excluded while preparing requests.

string

required

Maximum quoted charge in US dollars as a decimal string.

"USD"

required

Currency of the quote; always USD.

string | null

required

Deadline assigned to confirm this quote, as an ISO 8601 timestamp, or null when no deadline was assigned.

string | null

required

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

object | null

required

Output counts and token usage, or null before results are available.

Show Fields

number

required

Number of generated answers written.

number

required

Number of failed, missing, or unusable answers.

number

required

Number of answers truncated during generation.

number

required

Input tokens reported for successfully written answers.

number

required

Output tokens reported for successfully written answers.

object

required

Counts of request failures, keyed by error code.

Show Fields

number

object[]

required

Sample of request failures, up to 20 entries.See the HTTP endpoint for the complete schema.

string

required

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

string

required

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

Errors

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

Status	Description
409	Idempotency key reused for a different request
429	Rate limit exceeded

HTTP endpoint: POST /projects/{projectId}/batch-inference-runs.

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

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

const run = await client.batchInference.createRun({
  projectId: "pp.019a0000-0000-7000-8000-000000000001",
  idempotencyKey: crypto.randomUUID(),
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  model: {
    type: "base_model",
    baseModelId: "qwen3-4b"
  },
  sampling: {
    maxOutputTokens: 256
  },
  output: {
    type: "field",
    fieldName: "answer"
  }
});
console.log(run);

{
  "id": "bir.019a0000-0000-7000-8000-000000000001",
  "projectId": "pp.019a0000-0000-7000-8000-000000000001",
  "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
  "model": {
    "type": "base_model",
    "baseModelId": "qwen3-4b"
  },
  "mode": {
    "type": "single_turn"
  },
  "sampling": {
    "maxOutputTokens": 1
  },
  "output": {
    "type": "field",
    "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
    "fieldId": "df.019a0000-0000-7000-8000-000000000001"
  },
  "status": "preparing",
  "progress": null,
  "blockedReason": null,
  "message": null,
  "error": null,
  "quote": null,
  "chargedAmount": null,
  "result": null,
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}

Reference

TypeScript SDK

CLI

HTTP API

client.batchInference.createRun()

Signature

Parameters

Returns

Errors

​Signature

​Parameters

​Returns

​Errors

Signature

Parameters

Returns

Errors