> ## 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. # Create a batch inference run > 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. ## OpenAPI ````yaml /api-reference/openapi.json post /projects/{projectId}/batch-inference-runs openapi: 3.1.0 info: description: >- Manage projects, datasets, labeling pipelines, and model training. **Beta:** endpoints, request and response shapes, and error contracts can change without notice or a backward-compatibility promise. title: Toloka Platform API version: 2.0.0 servers: - url: https://platform.toloka.ai/api/v2-beta security: - apiKeyAuth: [] - scopedTokenAuth: [] tags: - description: The authenticated API key owner. name: Account - description: A project is the container for pipelines, datasets, and files. name: Projects - description: Rows and typed fields. Field schemas are immutable once created. name: Datasets - description: Append rows to a dataset from a file. name: Dataset uploads - description: Read a dataset out as a file. name: Dataset exports - description: A pipeline is a graph of nodes that processes each dataset item. name: Pipelines - description: The nodes, connections, fields, and version of a pipeline graph. name: Pipeline graph - description: Execute a pipeline over a dataset and inspect each item. name: Runs - description: Per-node checks that a pipeline must pass before deployment. name: Checks - description: Named credentials available to pipeline code. name: Secrets - description: Project files available to pipeline code and labeling interfaces. name: Files - description: >- Global, read-only catalog of the models a synthetic generation node can use, with their budget bounds. name: Generation models - description: >- Global, read-only catalog of the expert audience: the values a node `audience` filter can use. name: Audience - description: >- Project lists of experts a node can take its workforce from with `audienceMode: service`. Available only to teams with the audience service enabled. name: Expert lists - description: >- Experts banned in a project: they cannot be invited and are removed from the work they are in. Available only to teams with expert bans enabled. name: Expert ban list - description: Global, read-only base model catalog. name: Base models - description: Project-owned mutable model-training drafts. name: Trainings - description: Project-owned Models and immutable Model Versions. name: Models - name: Batch inference paths: /projects/{projectId}/batch-inference-runs: post: tags: - Batch inference summary: Create a batch inference run description: >- 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. operationId: createBatchInferenceRun parameters: - in: path name: projectId required: true schema: $ref: '#/components/schemas/ProjectId' - description: A caller-generated key reused for retries of one logical request. in: header name: idempotency-key required: true schema: maxLength: 128 minLength: 1 type: string requestBody: content: application/json: schema: additionalProperties: false description: Rows of one dataset to answer with one model. properties: datasetId: description: 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}$ type: string itemFilter: additionalProperties: false description: Filter selecting rows to answer; omit to include all rows. properties: excludeParts: $ref: '#/components/schemas/DatasetSplitPartExclusions' fieldSources: $ref: '#/components/schemas/DatasetFieldSourceConditions' fieldValues: $ref: '#/components/schemas/DatasetFieldValueConditions' missingRevisionFields: description: >- Field IDs with prefix `df.` that must have no revision on a selected row; defaults to an empty array. items: pattern: >- ^df\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string type: array parts: $ref: '#/components/schemas/DatasetSplitPartInclusion' slice: $ref: '#/components/schemas/DatasetSliceSelection' type: object mode: $ref: '#/components/schemas/BatchInferenceMode' model: $ref: '#/components/schemas/BatchInferenceModel' output: description: >- Where completions land: a text field on the source dataset, or a new chat-sft dataset. oneOf: - additionalProperties: false properties: fieldName: description: >- Name of the text field to receive the generated answers. maxLength: 128 minLength: 1 pattern: ^[a-z]([a-z0-9_]*[a-z0-9])?$ type: string type: const: field description: >- Output destination: `field` writes a text field in the source dataset; `dataset` creates a chat training dataset. type: string required: - type - fieldName type: object - additionalProperties: false properties: name: description: >- Name of the new dataset that will receive the generated answers. maxLength: 255 minLength: 1 type: string type: const: dataset description: >- Output destination: `field` writes a text field in the source dataset; `dataset` creates a chat training dataset. type: string required: - type - name type: object sampling: additionalProperties: false description: >- Generation settings for every model call: maxOutputTokens caps each answer and bounds the quote, and samplesPerRow is how many answers each row gets. properties: maxOutputTokens: description: >- Maximum number of generated tokens per answer, from 1 to 8192. maximum: 8192 minimum: 1 type: integer samplesPerRow: default: 1 description: >- Number of answers to generate for each row, from 1 to 16; defaults to 1. maximum: 16 minimum: 1 type: integer seed: description: Optional sampling seed, from 0 to 2147483647. maximum: 2147483647 minimum: 0 type: integer stop: description: >- One to four strings that stop generation when encountered; absent when no stop strings are set. items: maxLength: 64 minLength: 1 type: string maxItems: 4 minItems: 1 type: array temperature: default: 0 description: Sampling temperature from 0 to 2; defaults to 0. maximum: 2 minimum: 0 type: number topP: description: >- Cumulative probability cutoff for nucleus sampling, greater than 0 and at most 1; omit to use the model default. exclusiveMinimum: 0 maximum: 1 type: number required: - maxOutputTokens type: object required: - datasetId - model - sampling - output type: object responses: '200': content: application/json: schema: $ref: '#/components/schemas/BatchInferenceRun' description: Batch Inference Run preparing its quote headers: RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' '409': description: Idempotency key reused for a different request headers: RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' '429': description: Rate limit exceeded headers: RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' X-Request-Id: $ref: '#/components/headers/X-Request-Id' x-codeSamples: - label: TypeScript SDK lang: typescript source: | 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); components: schemas: ProjectId: description: 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}$ type: string DatasetSplitPartExclusions: description: Split-part selections to exclude; omit when no parts should be excluded. items: additionalProperties: false description: Split field and selected part names. properties: fieldId: description: Split field ID with prefix `df.`. pattern: >- ^df\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string names: description: Names of the split parts to select. items: maxLength: 64 pattern: ^[A-Za-z0-9_]+(?:[.-][A-Za-z0-9_]+)*$ type: string maxItems: 10 minItems: 1 type: array required: - fieldId - names type: object maxItems: 500 type: array DatasetFieldSourceConditions: description: >- Field-author conditions that selected rows must satisfy; defaults to no conditions. items: additionalProperties: false description: Required authors for a field. properties: fieldId: description: Dataset field ID with prefix `df.`. pattern: >- ^df\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string sources: description: Revision authors to match for this field. items: $ref: '#/components/schemas/FieldRevisionSource' minItems: 1 type: array required: - fieldId - sources type: object type: array DatasetFieldValueConditions: description: >- Field-value conditions that selected rows must satisfy; defaults to no conditions. items: additionalProperties: false description: Condition applied to a field value. properties: fieldId: description: Dataset field ID with prefix `df.` to compare. pattern: >- ^df\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string jsonPath: description: JSONPath locating the value within the field. minLength: 1 type: string latestOnly: default: true description: >- Whether to test only the latest revision from the allowed authors; false tests any revision, and the default is true. type: boolean operator: description: >- Text comparison: `text_eq` for equality or `text_neq` for inequality. enum: - text_eq - text_neq type: string sources: default: [] description: Allowed revision authors; an empty array allows any author. items: $ref: '#/components/schemas/FieldRevisionSource' type: array value: description: Scalar value compared as text; null is treated as an empty string. type: - string - number - boolean - 'null' required: - jsonPath - operator - value - fieldId type: object type: array DatasetSplitPartInclusion: additionalProperties: false description: Split parts to include; omit to include every part. properties: fieldId: description: Split field ID with prefix `df.`. pattern: >- ^df\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string names: description: Names of the split parts to select. items: maxLength: 64 pattern: ^[A-Za-z0-9_]+(?:[.-][A-Za-z0-9_]+)*$ type: string maxItems: 10 minItems: 1 type: array required: - fieldId - names type: object DatasetSliceSelection: additionalProperties: false description: >- Slice whose frozen rows and fields to read; omit to use live dataset rows. properties: sliceId: description: Dataset slice ID with prefix `dsl.`. pattern: >- ^dsl\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string required: - sliceId type: object BatchInferenceMode: description: >- 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`. oneOf: - additionalProperties: false properties: type: const: single_turn description: >- Processing mode; `single_turn` makes one model call for each requested sample of a row. type: string required: - type type: object BatchInferenceModel: description: >- 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`. oneOf: - additionalProperties: false properties: baseModelId: description: Catalog base model identifier. enum: - qwen3-4b - qwen3-8b - qwen3-32b - qwen3-235b type: string type: const: base_model description: >- Model source: `base_model` uses a catalog model; `model_version` uses a published project model version. type: string required: - type - baseModelId type: object - additionalProperties: false properties: modelVersionId: description: Model version ID with prefix `mdv.`. pattern: >- ^mdv\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string type: const: model_version description: >- Model source: `base_model` uses a catalog model; `model_version` uses a published project model version. type: string required: - type - modelVersionId type: object BatchInferenceRun: description: >- A batch inference run with its quote, progress, charge, and output location. properties: blockedReason: anyOf: - enum: - funds - payment - billing_review type: string - type: 'null' description: >- Reason the run is blocked: `funds` to reserve the budget, `payment` to settle usage, or `billing_review` for staff review; otherwise null. chargedAmount: anyOf: - pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$ type: string - type: 'null' description: >- Settled charge in US dollars as a decimal string, or null before a charge is recorded. createdAt: description: Time the batch inference run was created, as an ISO 8601 timestamp. format: date-time 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))$ type: string datasetId: $ref: '#/components/schemas/DatasetId' error: anyOf: - properties: code: anyOf: - enum: - requests_export_failed - no_requests - selection_too_large - billing_rejected - provider_failed - provider_timeout - invalid_provider_output - output_rejected - payment_window_expired type: string - const: canceled type: string description: Machine-readable reason the run failed or was canceled. message: description: Explanation of the failure or cancellation. maxLength: 500 type: string required: - code - message type: object - type: 'null' description: Failure or cancellation details, or null when no error is recorded. id: $ref: '#/components/schemas/BatchInferenceRunId' message: description: >- Current status or billing explanation, or null when none is available. type: - string - 'null' mode: $ref: '#/components/schemas/BatchInferenceMode' model: $ref: '#/components/schemas/BatchInferenceModel' output: description: Dataset and field where this run writes completions. properties: datasetId: $ref: '#/components/schemas/DatasetId' fieldId: $ref: '#/components/schemas/DatasetFieldId' type: description: >- Output destination: `field` writes to the source dataset, while `dataset` writes to a new dataset. enum: - field - dataset type: string required: - type - datasetId - fieldId type: object progress: anyOf: - additionalProperties: false properties: phase: description: >- Generation phase: `queued`, `preparing` inputs, `generating` answers, or `finishing` results. enum: - queued - preparing - generating - finishing type: string requests: additionalProperties: false description: >- Request progress; absent when request counts are unavailable. properties: done: description: Number of model requests completed. maximum: 9007199254740991 minimum: 0 type: integer total: description: Total number of model requests. maximum: 9007199254740991 minimum: 0 type: integer required: - done - total type: object required: - phase type: object - type: 'null' description: >- Latest generation progress while running or stopping; null in other states or when progress is unavailable. projectId: $ref: '#/components/schemas/ProjectId' quote: anyOf: - properties: confirmBefore: anyOf: - format: date-time 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))$ type: string - type: 'null' description: >- Deadline assigned to confirm this quote, as an ISO 8601 timestamp, or null when no deadline was assigned. currency: const: USD description: Currency of the quote; always `USD`. type: string maximumCharge: description: Maximum quoted charge in US dollars as a decimal string. pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$ type: string requests: description: Number of model requests included in the quote. exclusiveMinimum: 0 maximum: 9007199254740991 type: integer skippedRows: description: Number of selected rows excluded while preparing requests. maximum: 9007199254740991 minimum: 0 type: integer required: - requests - skippedRows - maximumCharge - currency - confirmBefore type: object - type: 'null' description: Price quote for confirmation, or null before a quote is ready. result: anyOf: - additionalProperties: false properties: errorCounts: additionalProperties: exclusiveMinimum: 0 maximum: 9007199254740991 type: integer description: Counts of request failures, keyed by error code. propertyNames: maxLength: 64 minLength: 1 type: string type: object errorSamples: description: Sample of request failures, up to 20 entries. items: additionalProperties: false properties: code: description: Machine-readable request failure code. maxLength: 64 minLength: 1 type: string itemId: description: >- Identifier of the source dataset item associated with the failed request. maxLength: 128 minLength: 1 type: string message: description: Explanation of the request failure. minLength: 1 type: string required: - itemId - code - message type: object maxItems: 20 type: array failed: description: Number of failed, missing, or unusable answers. maximum: 9007199254740991 minimum: 0 type: integer inputTokens: description: Input tokens reported for successfully written answers. maximum: 9007199254740991 minimum: 0 type: integer outputTokens: description: Output tokens reported for successfully written answers. maximum: 9007199254740991 minimum: 0 type: integer truncated: description: Number of answers truncated during generation. maximum: 9007199254740991 minimum: 0 type: integer written: description: Number of generated answers written. maximum: 9007199254740991 minimum: 0 type: integer required: - written - failed - truncated - inputTokens - outputTokens - errorCounts - errorSamples type: object - type: 'null' description: Output counts and token usage, or null before results are available. sampling: additionalProperties: false description: Generation settings used for each model call. properties: maxOutputTokens: description: Maximum number of generated tokens per answer, from 1 to 8192. maximum: 8192 minimum: 1 type: integer samplesPerRow: default: 1 description: >- Number of answers to generate for each row, from 1 to 16; defaults to 1. maximum: 16 minimum: 1 type: integer seed: description: Optional sampling seed, from 0 to 2147483647. maximum: 2147483647 minimum: 0 type: integer stop: description: >- One to four strings that stop generation when encountered; absent when no stop strings are set. items: maxLength: 64 minLength: 1 type: string maxItems: 4 minItems: 1 type: array temperature: default: 0 description: Sampling temperature from 0 to 2; defaults to 0. maximum: 2 minimum: 0 type: number topP: description: >- Cumulative probability cutoff for nucleus sampling, greater than 0 and at most 1; omit to use the model default. exclusiveMinimum: 0 maximum: 1 type: number required: - maxOutputTokens type: object status: description: >- 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. enum: - preparing - awaiting_confirmation - queued - running - writing_outputs - stopping - blocked - completed - failed - canceled type: string updatedAt: description: >- Time the batch inference run was last updated, as an ISO 8601 timestamp. format: date-time 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))$ type: string required: - id - projectId - datasetId - model - mode - sampling - output - status - progress - blockedReason - message - error - quote - chargedAmount - result - createdAt - updatedAt type: object FieldRevisionSource: description: Source that wrote a field revision. oneOf: - additionalProperties: false description: Source that wrote a field revision. properties: type: const: user description: >- Revision author: `user` for a user action or `system` for a platform operation. type: string userId: description: Identifier of the user who wrote the revision. minLength: 1 type: string required: - type - userId type: object - additionalProperties: false description: Source that wrote a field revision. properties: source: description: Identifier of the platform operation that wrote the revision. minLength: 1 type: string type: const: system description: >- Revision author: `user` for a user action or `system` for a platform operation. type: string required: - type - source type: object DatasetId: description: 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}$ type: string BatchInferenceRunId: description: 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}$ type: string DatasetFieldId: description: Dataset field ID with prefix `df.`. pattern: >- ^df\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$ type: string headers: RateLimit-Limit: description: The maximum number of requests allowed in the current window. schema: type: integer RateLimit-Policy: description: The rate limit policy (e.g., "60;w=60"). schema: type: string RateLimit-Remaining: description: The number of requests remaining in the current window. schema: type: integer RateLimit-Reset: description: The number of seconds until the current window resets. schema: type: integer X-Request-Id: description: >- The request id: the X-Request-Id you sent when it is 1-128 characters of letters, digits, ".", "_" or "-", otherwise a generated UUID. Present on every response, including errors; quote it when reporting a problem. schema: type: string securitySchemes: apiKeyAuth: description: >- Enter `ApiKey ` in Authorization, including the `ApiKey ` prefix. In cURL and Python samples, `` means this full value. The TypeScript SDK adds the prefix for you. in: header name: Authorization type: apiKey scopedTokenAuth: description: >- Enter the project-scoped token as `pst_...` in X-Scoped-Token, without an `ApiKey ` prefix. Create a token with POST /projects/{projectId}/tokens. in: header name: X-Scoped-Token type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.