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

# client.runs.start()

> Start a pipeline run.

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`:

```ts theme={null}
start(args: {
  pipelineId: string;
}): Promise<RunJob>;
```

## Parameters

**pipelineId** `string` *required*

Pipeline ID with prefix `pl.`.

## Returns

`Promise<RunJob>`

A pipeline run job. Poll until status is succeeded or failed.

**id** `RunId` *required*

Pipeline run ID with prefix `plr.`.

**datasetId** `DatasetId` *required*

Dataset ID with prefix `ds.`.

**status** `"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`.

**createdAt** `string` *required*

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

**error** `string | null` *required*

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

**result** `RunStats` *required*

Counts of items and their current outcomes.

**Fields**

**total** `number` *required*

Total number of items in this run.

**completed** `number` *required*

Number of items that completed successfully.

**failed** `number` *required*

Number of items that failed.

**canceled** `number` *required*

Number of items that were canceled.

**paused** `number` *required*

Number of items currently paused.

## Errors

HTTP errors throw [`PotatoApiError`](https://docs.platform.toloka.ai/docs/sdk/errors). 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`](https://docs.platform.toloka.ai/docs/api-reference/runs/create-pipeline-run).

```ts start() theme={null}
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);
```

```json start() theme={null}
{
  "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
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.