Create a batch inference run

TypeScript SDK

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);

curl --request POST \
  --url https://platform.toloka.ai/api/v2-beta/projects/{projectId}/batch-inference-runs \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "datasetId": "<string>",
  "model": {
    "type": "base_model"
  },
  "output": {
    "fieldName": "<string>",
    "type": "field"
  },
  "sampling": {
    "maxOutputTokens": 4096,
    "samplesPerRow": 1,
    "seed": 1073741823,
    "stop": [
      "<string>"
    ],
    "temperature": 0,
    "topP": 0
  }
}
'

import requests

url = "https://platform.toloka.ai/api/v2-beta/projects/{projectId}/batch-inference-runs"

payload = {
    "datasetId": "<string>",
    "model": { "type": "base_model" },
    "output": {
        "fieldName": "<string>",
        "type": "field"
    },
    "sampling": {
        "maxOutputTokens": 4096,
        "samplesPerRow": 1,
        "seed": 1073741823,
        "stop": ["<string>"],
        "temperature": 0,
        "topP": 0
    }
}
headers = {
    "idempotency-key": "<idempotency-key>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "blockedReason": "funds",
  "chargedAmount": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "datasetId": "<string>",
  "error": {
    "code": "requests_export_failed",
    "message": "<string>"
  },
  "id": "<string>",
  "message": "<string>",
  "mode": {
    "type": "single_turn"
  },
  "model": {
    "baseModelId": "qwen3-4b",
    "type": "base_model"
  },
  "output": {
    "datasetId": "<string>",
    "fieldId": "<string>",
    "type": "field"
  },
  "progress": {
    "phase": "queued",
    "requests": {
      "done": 4503599627370495,
      "total": 4503599627370495
    }
  },
  "projectId": "<string>",
  "quote": {
    "confirmBefore": "2023-11-07T05:31:56Z",
    "currency": "USD",
    "maximumCharge": "<string>",
    "requests": 123,
    "skippedRows": 4503599627370495
  },
  "result": {
    "errorCounts": {},
    "errorSamples": [
      {
        "code": "<string>",
        "itemId": "<string>",
        "message": "<string>"
      }
    ],
    "failed": 4503599627370495,
    "inputTokens": 4503599627370495,
    "outputTokens": 4503599627370495,
    "truncated": 4503599627370495,
    "written": 4503599627370495
  },
  "sampling": {
    "maxOutputTokens": 4096,
    "samplesPerRow": 1,
    "seed": 1073741823,
    "stop": [
      "<string>"
    ],
    "temperature": 0,
    "topP": 0
  },
  "status": "preparing",
  "updatedAt": "2023-11-07T05:31:56Z"
}

POST

projects

{projectId}

batch-inference-runs

TypeScript SDK

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);

curl --request POST \
  --url https://platform.toloka.ai/api/v2-beta/projects/{projectId}/batch-inference-runs \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "datasetId": "<string>",
  "model": {
    "type": "base_model"
  },
  "output": {
    "fieldName": "<string>",
    "type": "field"
  },
  "sampling": {
    "maxOutputTokens": 4096,
    "samplesPerRow": 1,
    "seed": 1073741823,
    "stop": [
      "<string>"
    ],
    "temperature": 0,
    "topP": 0
  }
}
'

import requests

url = "https://platform.toloka.ai/api/v2-beta/projects/{projectId}/batch-inference-runs"

payload = {
    "datasetId": "<string>",
    "model": { "type": "base_model" },
    "output": {
        "fieldName": "<string>",
        "type": "field"
    },
    "sampling": {
        "maxOutputTokens": 4096,
        "samplesPerRow": 1,
        "seed": 1073741823,
        "stop": ["<string>"],
        "temperature": 0,
        "topP": 0
    }
}
headers = {
    "idempotency-key": "<idempotency-key>",
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "blockedReason": "funds",
  "chargedAmount": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "datasetId": "<string>",
  "error": {
    "code": "requests_export_failed",
    "message": "<string>"
  },
  "id": "<string>",
  "message": "<string>",
  "mode": {
    "type": "single_turn"
  },
  "model": {
    "baseModelId": "qwen3-4b",
    "type": "base_model"
  },
  "output": {
    "datasetId": "<string>",
    "fieldId": "<string>",
    "type": "field"
  },
  "progress": {
    "phase": "queued",
    "requests": {
      "done": 4503599627370495,
      "total": 4503599627370495
    }
  },
  "projectId": "<string>",
  "quote": {
    "confirmBefore": "2023-11-07T05:31:56Z",
    "currency": "USD",
    "maximumCharge": "<string>",
    "requests": 123,
    "skippedRows": 4503599627370495
  },
  "result": {
    "errorCounts": {},
    "errorSamples": [
      {
        "code": "<string>",
        "itemId": "<string>",
        "message": "<string>"
      }
    ],
    "failed": 4503599627370495,
    "inputTokens": 4503599627370495,
    "outputTokens": 4503599627370495,
    "truncated": 4503599627370495,
    "written": 4503599627370495
  },
  "sampling": {
    "maxOutputTokens": 4096,
    "samplesPerRow": 1,
    "seed": 1073741823,
    "stop": [
      "<string>"
    ],
    "temperature": 0,
    "topP": 0
  },
  "status": "preparing",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization

string

header

required

Enter ApiKey <your-api-key> in Authorization, including the ApiKey prefix. In cURL and Python samples, <api-key> means this full value. The TypeScript SDK adds the prefix for you.

Headers

idempotency-key

string

required

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

Required string length: 1 - 128

Path Parameters

projectId

string

required

Project ID with prefix pp..

Pattern: ^pp\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Body

application/json

Rows of one dataset to answer with one model.

datasetId

string

required

Source dataset ID with prefix ds..

Pattern: ^ds\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

model

object

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.

Option 1
Option 2

Show child attributes

output

object

required

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

Option 1
Option 2

Show child attributes

sampling

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 child attributes

itemFilter

object

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

Show child attributes

mode

object

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 child attributes

Response

Batch Inference Run preparing its quote

A batch inference run with its quote, progress, charge, and output location.

blockedReason

enum<string> | null

required

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

Available options:

funds,

payment,

billing_review

chargedAmount

string | null

required

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

Pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$

createdAt

string<date-time>

required

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

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

datasetId

string

required

Dataset ID with prefix ds..

Pattern: ^ds\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

error

object | null

required

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

Show child attributes

string

required

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

Pattern: ^bir\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

message

string | null

required

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

mode

object

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 child attributes

model

object

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.

Option 1
Option 2

Show child attributes

output

object

required

Dataset and field where this run writes completions.

Show child attributes

progress

object | null

required

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

Show child attributes

projectId

string

required

Project ID with prefix pp..

Pattern: ^pp\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

quote

object | null

required

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

Show child attributes

result

object | null

required

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

Show child attributes

sampling

object

required

Generation settings used for each model call.

Show child attributes

status

enum<string>

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.

Available options:

preparing,

awaiting_confirmation,

queued,

running,

writing_outputs,

stopping,

blocked,

completed,

failed,

canceled

updatedAt

string<date-time>

required

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

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Reference

TypeScript SDK

CLI

HTTP API

Create a batch inference run

Authorizations

Headers

Path Parameters

Body

Response