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

# Long-running jobs

> Wait for background work and distinguish completion, failure, and timeouts.

Dataset uploads, exports, pipeline checks, pipeline runs, slices, splits, and field operations can continue after the initiating request returns. Use [`client.waitFor`](https://docs.platform.toloka.ai/docs/sdk/reference/wait-for) to poll for completion.

The default timeout is **60,000 ms** and the default interval is **1,000 ms**. The first poll starts immediately; the interval is the delay between subsequent polls. Choose a longer interval for slow work or when several jobs share an endpoint's [rate limit](https://docs.platform.toloka.ai/docs/sdk/client.md#rate-limits-and-retries).

## Wait for an export

Call [`datasets.startExport()`](https://docs.platform.toloka.ai/docs/sdk/reference/datasets/start-export) using `client.ts` from the [quickstart](https://docs.platform.toloka.ai/docs/sdk/quickstart.md#2-create-a-client). Replace the dataset ID and field names with yours.

```ts theme={null}
import { client } from "./client";

const started = await client.datasets.startExport({
  datasetId: "ds.019ffa5f-29a7-74de-a76c-7ba5ceedf37f",
  fields: ["text", "label"],
});

const job = await client.waitFor(
  { type: "datasetExport", exportId: started.id },
  { timeoutMs: 120_000, intervalMs: 2_000 },
);

if (job.status === "failed") {
  console.error(job.error?.code, job.error?.message);
} else {
  console.log(job.result.downloadUrl);
}
```

## Choose a wait target

| `type` | Other target properties | Returns | Stops when |
| - | - | - | - |
| `datasetUpload` | `uploadId` | `TerminalJob<UploadJob>` | `status` is `succeeded` or `failed` |
| `datasetExport` | `exportId` | `TerminalJob<ExportJob>` | `status` is `succeeded` or `failed` |
| `pipelineCheck` | `checkRunId` | `TerminalJob<CheckJob>` | `status` is `succeeded` or `failed` |
| `pipelineRun` | `runId` | `TerminalJob<RunJob>` | `status` is `succeeded` or `failed` |
| `datasetSlice` | `sliceId` | `DatasetSlice` | `status` is `ready` or `failed` |
| `datasetSplit` | `datasetId`, `column` | `DatasetField` | `split.status` is `ready` or `failed` |
| `datasetFields` | `datasetId`, optional `names` | `DatasetField[]` | No watched field has an operation with `blocking: true` |

`datasetFields` returns all fields in the dataset. `names` only narrows which fields it waits on. It can finish immediately when the named fields are absent or have no blocking operations; it does not check that fields were created or that work succeeded. `datasetSplit` requires an existing split field and throws if `column` is missing or is not a split field.

Uploads must be finalized before ingestion can complete. PUT the file bytes to the returned `uploadUrl` with the header `x-ms-blob-type: BlockBlob` and the file's `Content-Type`. After a successful upload response, call [`datasets.finalizeUpload`](https://docs.platform.toloka.ai/docs/sdk/reference/datasets/finalize-upload), then wait for the job. Waiting without transferring the bytes and finalizing leaves the job pending. See the [upload endpoint](https://docs.platform.toloka.ai/docs/api-reference/dataset-uploads/create-dataset-upload.md).

Training Runs and Batch Inference Runs have their own states and no [`waitFor`](https://docs.platform.toloka.ai/docs/sdk/reference/wait-for) target. Read them with [`trainings.getRun`](https://docs.platform.toloka.ai/docs/sdk/reference/trainings/get-run) and [`batchInference.getRun`](https://docs.platform.toloka.ai/docs/sdk/reference/batch-inference/get-run); see the [client method index](https://docs.platform.toloka.ai/docs/sdk/reference/client-methods.md).

## Handle failure and timeout

A job that reaches `failed` is **returned**, not thrown. Inspect the returned status and error. Slices expose `error`; splits expose `split.error`. For checks, inspect `result` as well as the job status.

A timeout throws `PotatoApiError` with `code: "wait_timeout"`, no HTTP `status`, and `body: { timeoutMs }`. It stops waiting; it does not cancel the job. Keep the job ID so you can read or wait for it again. HTTP failures during polling throw immediately. See [errors](https://docs.platform.toloka.ai/docs/sdk/errors.md).

## Poll yourself

Use the corresponding read method when you need progress updates, your own scheduling, or a durable job monitor.

| Work | Read method |
| - | - |
| Upload | [`datasets.getUpload({ uploadId })`](https://docs.platform.toloka.ai/docs/sdk/reference/datasets/get-upload) |
| Export | [`datasets.getExport({ exportId })`](https://docs.platform.toloka.ai/docs/sdk/reference/datasets/get-export) |
| Pipeline check | [`checks.get({ checkRunId })`](https://docs.platform.toloka.ai/docs/sdk/reference/checks/get) |
| Pipeline run | [`runs.get({ runId })`](https://docs.platform.toloka.ai/docs/sdk/reference/runs/get) |
| Slice | [`datasets.getSlice({ sliceId })`](https://docs.platform.toloka.ai/docs/sdk/reference/datasets/get-slice) |
| Split | [`datasets.listFieldsPage({ datasetId, names: column })`](https://docs.platform.toloka.ai/docs/sdk/reference/datasets/list-fields) |
| Field operations | [`datasets.listAllFields({ datasetId })`](https://docs.platform.toloka.ai/docs/sdk/reference/datasets/list-fields) |

Each call reads the current state once. Schedule another read while it is still running, and stop on the terminal states above.


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