Skip to main content
The beta HTTP API covers shared projects and datasets, Data Labeling pipelines, and Train. Authenticate once, then use the same project IDs and team permissions across both products. The typed endpoint reference is the canonical inventory of paths, parameters, and response shapes.
The API is in beta: its request and response shapes can change without a backward-compatibility promise. Expect to revisit your integration as the platform changes.

​
Before you start

You need:
  • Access to a team in the Toloka platform.
  • An API key. You generate it yourself in the Business Console, the application the platform’s Top up and Billing history buttons open (see Manage your team and balance). Open your company there, switch to its API keys tab, and click Generate API key. The same tab lists your existing keys and deletes one.

​
Connect

The API is served at:
Endpoint paths in the API reference are relative to this base URL. Authenticate every request with your API key in the Authorization header:

​
The endpoint reference

  • API reference, with public endpoints, parameters, response shapes, and TypeScript SDK examples.
  • OpenAPI 3.1 document, served by the deployed API as JSON for generating a client.
Use the TypeScript SDK as a typed client for these endpoints.

​
Your first call

List your projects to check the connection. The call needs only a key and does not modify data:
A working key returns your projects across your teams — an empty list if you have none. A 401 with Unauthenticated means the key or the header is wrong; see Troubleshooting.

​
Data Labeling

The Data Labeling API can create projects and datasets, load items, import or copy pipelines, start pipeline runs, and export results:
  • Uploading items, running a pipeline, and exporting results are long-running jobs. Create the job, then poll the matching GET endpoint until it reports succeeded or failed.
  • Post rows directly to a dataset, up to 2 MB and 10,000 rows per call. For larger data, start an upload with a format of json, jsonl, or csv and declare the file size, which the upload holds you to. JSON is an array of row objects; JSONL is one row object per nonempty line. PUT the file to the returned link, finalize, and poll. Files run up to 1024 MB.
  • Read or replace a pipeline’s nodes and connections through its graph endpoints, import a .pipeline file, or copy a pipeline. Then attach a dataset and start a run. The attach call takes the same itemLimit and itemFilter as the Start node’s controls. See Start and End nodes.
  • List item IDs and indexes with GET /datasets/:datasetId/items. To read field values, start an export job and fetch the result from its download link.

​
Train

  • List and inspect the Base model catalog.
  • Split a dataset into train, validation, and test parts and freeze a dataset slice.
  • Create and list Trainings in a project, read or rename a Training, and replace its configuration.
  • Prepare cost-estimate inputs, calculate an estimate, and start or list Training Runs.
  • Read a Training Run, logs, current metrics, and metric history; resume or cancel when its state allows the operation.
  • Create, list, read, and archive Models; list Model Versions; inspect and download Model Version content.
A Training configuration requires sliceId for a ready slice that freezes a split column. Set splitFieldId when the slice freezes more than one split column. Optional trainParts selects an array of part names with the train role; omitting it selects every train part. The platform derives validation rows from all parts with the validate role and keeps test rows out of learning. Creating a split column without specifying parts uses 80% train, 10% validation, and 10% test. If the slice supplies no validation rows, Training holds out 10% of the selected train rows. Rows added after a split have no part, so a new slice alone leaves them out of Training. To include them, send POST /datasets/:datasetId/split with the same column and no parts; rows that already have a part keep it. Wait until that column’s split status in GET /datasets/:datasetId/fields is ready, create a slice with POST /datasets/:datasetId/slices, wait until GET /slices/:sliceId reports ready, then replace the Training configuration with the new sliceId. For changed values in frozen fields alone, the new slice is enough. See Slices and split columns for the matching CLI commands. For the resource lifecycle, see How Training works; for the billing step, see Training cost.

​
Shared request behavior

The rate limit is 60 requests per minute per endpoint route and authenticated user. Responses processed by the rate limiter include RateLimit-* headers; earlier authentication or scope errors can omit them. Exceeding the limit returns 429. State-changing requests (POST, PUT, PATCH, DELETE) must carry Content-Type: application/json and a JSON body, {} when the endpoint takes none. A request without a content type is treated as a cross-site form submission and rejected with 403 Forbidden: the request looks like a cross-site form submission. Non-browser clients must send Content-Type: application/json with a JSON body on state-changing requests. Every response carries X-Request-Id: the value you sent when it is 1–128 characters of letters, digits, ., _ or -, otherwise a generated UUID. Error responses carry it too. Quote it when you report a problem; it is the key our logs are searched by.

​
Data Labeling sharp edges

After cancellation, GET /runs/:runId returns failed with the error Run canceled. Cancel works only once the run is deployed. Canceling during deployment, canceling twice, or canceling while the run is being finalized returns 409. The cancel body accepts an optional pendingHumanQa: An unknown field or value returns 400. See Resume or cancel a run.
  • Completed items return state.output. Canceled items can return state.partialOutput with the same shape, containing End-node fields that had values when cancellation occurred. This can include outputs accepted without review. It is null for other statuses and for canceled items where no node wrote an End-node field.
  • Dataset export status is running, succeeded, or failed. Stop polling on either terminal status. On failed, inspect error and correct the cause before creating another export.
  • API deploys use the same lint gate as the web app: unfinished built-in lints, configuration errors, and failed checks block the deploy. Resolve them before starting a run.
  • A dataset export over the API returns the dataset’s own fields, not the per-item pipeline-run export documented in Export format.
  • A pipeline run processes at most 10,000 items. A dataset holds at most 150,000 items, and each field value can be up to 1 MiB. See labeling in batches and managing datasets.

​
Permissions

A team that has not completed required identity or business verification can be restricted to one project and one pipeline and prevented from starting a pipeline run. These refusals return 403. Complete the verification flow offered to the team in the web app. An API key acts as its owner and inherits that user’s team permissions. Writes return: If an existing resource returns 404, check that your key belongs to the correct team.

​
Shared and Data Labeling troubleshooting

This table covers shared authentication and project errors plus Data Labeling pipeline and dataset errors. Train returns typed errors through the same API; interpret Training Run states with How Training works and use the served endpoint reference for each operation’s response schema. For every other Data Labeling message, search Dataset and pipeline errors.