client.runs.start()

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

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

const run = await client.runs.start({
  pipelineId: "pl.019a0000-0000-7000-8000-000000000001"
});
console.log(run);

{
  "id": "plr.019a0000-0000-7000-8000-000000000001",
  "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
  "status": "pending",
  "createdAt": "2026-01-01T00:00:00Z",
  "error": null,
  "result": {
    "total": 0,
    "completed": 0,
    "failed": 0,
    "canceled": 0,
    "paused": 0
  }
}

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

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

const run = await client.runs.start({
  pipelineId: "pl.019a0000-0000-7000-8000-000000000001"
});
console.log(run);

{
  "id": "plr.019a0000-0000-7000-8000-000000000001",
  "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
  "status": "pending",
  "createdAt": "2026-01-01T00:00:00Z",
  "error": null,
  "result": {
    "total": 0,
    "completed": 0,
    "failed": 0,
    "canceled": 0,
    "paused": 0
  }
}

Start processing the attached dataset, up to 10,000 items. Returns the run to poll. Configuration errors, failed checks, and unfinished lints on nodes from Start to End block deployment with 400. Missing lints and exam-dataset lints with findings are started when deployment is rejected; retry after they finish. Restart failed lints with POST /api/v2-beta/pipelines/{pipelineId}/lints.

Signature

Method signature on client.runs:

start(args: {
  pipelineId: string;
}): Promise<RunJob>;

Parameters

string

required

Pipeline ID with prefix pl..

Returns

Promise<RunJob> A pipeline run job. Poll until status is succeeded or failed.

RunId

required

Pipeline run ID with prefix plr..

DatasetId

required

Dataset ID with prefix ds..

"pending" | "running" | "succeeded" | "failed"

required

Run state: pending before deployment, running while processing, succeeded when processing ends, or failed if deployment fails; individual item failures are counted in result.

string

required

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

string | null

required

Deployment failure message, or null when the run deployed successfully.

RunStats

required

Counts of items and their current outcomes.

Show Fields

number

required

Total number of items in this run.

number

required

Number of items that completed successfully.

number

required

Number of items that failed.

number

required

Number of items that were canceled.

number

required

Number of items currently paused.

Errors

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

Status	Description
400	The pipeline cannot run: attach a dataset, stay within the item limit, and resolve unfinished or failed lints.
403	Not permitted for this team. An account that has not completed identity or business verification cannot start a run. Complete verification in the web app to lift the limit.
404	Pipeline not found
409	Pipeline already has an active run
429	Rate limit exceeded

HTTP endpoint: POST /pipelines/{pipelineId}/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.runs.start({
  pipelineId: "pl.019a0000-0000-7000-8000-000000000001"
});
console.log(run);

{
  "id": "plr.019a0000-0000-7000-8000-000000000001",
  "datasetId": "ds.019a0000-0000-7000-8000-000000000001",
  "status": "pending",
  "createdAt": "2026-01-01T00:00:00Z",
  "error": null,
  "result": {
    "total": 0,
    "completed": 0,
    "failed": 0,
    "canceled": 0,
    "paused": 0
  }
}

Reference

TypeScript SDK

CLI

HTTP API

Signature

Parameters

Returns

Errors

​Signature

​Parameters

​Returns

​Errors

Signature

Parameters

Returns

Errors