waitFor

import { client } from "./client";

const job = await client.waitFor(
  {
    type: "datasetExport",
    exportId: "dex.019ffa5f-29a7-74de-a76c-7ba5ceedf37f",
  },
  { timeoutMs: 120_000, intervalMs: 2_000 },
);

if (job.status === "failed") {
  throw new Error(job.error?.message ?? "Export failed");
}

console.log(job.result.downloadUrl);

{
  "id": "dex.019ffa5f-29a7-74de-a76c-7ba5ceedf37f",
  "datasetId": "ds.019ffa5f-29a7-74de-a76c-7ba5ceedf37f",
  "status": "succeeded",
  "createdAt": "2026-11-04T10:00:00Z",
  "result": { "downloadUrl": "https://example.com/export.json" },
  "report": null,
  "error": null
}

import { client } from "./client";

const job = await client.waitFor(
  {
    type: "datasetExport",
    exportId: "dex.019ffa5f-29a7-74de-a76c-7ba5ceedf37f",
  },
  { timeoutMs: 120_000, intervalMs: 2_000 },
);

if (job.status === "failed") {
  throw new Error(job.error?.message ?? "Export failed");
}

console.log(job.result.downloadUrl);

{
  "id": "dex.019ffa5f-29a7-74de-a76c-7ba5ceedf37f",
  "datasetId": "ds.019ffa5f-29a7-74de-a76c-7ba5ceedf37f",
  "status": "succeeded",
  "createdAt": "2026-11-04T10:00:00Z",
  "result": { "downloadUrl": "https://example.com/export.json" },
  "report": null,
  "error": null
}

waitFor is a method on the client returned by createClient. Its return type depends on the target:

import type {
  CheckJob,
  DatasetExportWaitTarget,
  DatasetField,
  DatasetFieldsWaitTarget,
  DatasetSlice,
  DatasetSliceWaitTarget,
  DatasetSplitWaitTarget,
  DatasetUploadWaitTarget,
  ExportJob,
  PipelineCheckWaitTarget,
  PipelineRunWaitTarget,
  RunJob,
  TerminalJob,
  UploadJob,
  WaitForOptions,
} from "@toloka-platform/sdk";

declare function waitFor(target: DatasetUploadWaitTarget, options?: WaitForOptions): Promise<TerminalJob<UploadJob>>;
declare function waitFor(target: DatasetExportWaitTarget, options?: WaitForOptions): Promise<TerminalJob<ExportJob>>;
declare function waitFor(target: PipelineCheckWaitTarget, options?: WaitForOptions): Promise<TerminalJob<CheckJob>>;
declare function waitFor(target: PipelineRunWaitTarget, options?: WaitForOptions): Promise<TerminalJob<RunJob>>;
declare function waitFor(target: DatasetSliceWaitTarget, options?: WaitForOptions): Promise<DatasetSlice>;
declare function waitFor(target: DatasetSplitWaitTarget, options?: WaitForOptions): Promise<DatasetField>;
declare function waitFor(target: DatasetFieldsWaitTarget, options?: WaitForOptions): Promise<DatasetField[]>;

Parameters

WaitForTarget

required

Select the operation and supply its ID. IDs accept strings.

Show Target variants

{ type: 'datasetUpload'; uploadId: string }

Waits until upload status is succeeded or failed.

{ type: 'datasetExport'; exportId: string }

Waits until export status is succeeded or failed.

{ type: 'pipelineCheck'; checkRunId: string }

Waits until check status is succeeded or failed.

{ type: 'pipelineRun'; runId: string }

Waits until run status is succeeded or failed.

{ type: 'datasetSlice'; sliceId: string }

Waits until slice status is no longer creating.

{ type: 'datasetSplit'; datasetId: string; column: string }

column is the split field’s name. Waits until split.status is no longer filling.

{ type: 'datasetFields'; datasetId: string; names?: readonly string[] }

Waits until no selected field has an operation with blocking: true. Omit names to watch every field. Returns all dataset fields, including those outside names.

WaitForOptions

default:"{}"

Polling limits.

Show Polling options

number

default:"60000"

Nonnegative finite timeout in milliseconds. Includes request time; timing out stops polling without canceling platform work.

number

default:"1000"

Positive finite delay in milliseconds between polls. The first poll starts immediately.

Returns

Promise

The final fetched resource, not only its result property.

Show Resolved value by target

TerminalJob<UploadJob>

Upload job with terminal status and result.itemsIngested.

TerminalJob<ExportJob>

Export job with terminal status, error, and result.downloadUrl.

TerminalJob<CheckJob>

Check job with terminal status and its result.

TerminalJob<RunJob>

Run job with terminal status and item counts in result.

DatasetSlice

Slice with status: "ready" or "failed".

DatasetField

Split field with split.status: "ready" or "failed".

DatasetField[]

All fields after watched blocking operations end. This does not establish success or the existence of every requested name.

A failed job is returned, not thrown. Inspect its error. See long-running jobs for upload finalization and alternative polling methods.

Throws

PotatoApiError with code: "wait_timeout" and body: { timeoutMs } when the timeout expires.
PotatoApiError with code: "http" when a polling request fails.
A local error for invalid polling options, or when datasetSplit cannot find the named split field.
Other errors from fetch or the credential callback are passed through.

Use client.ts from the quickstart and replace the export ID.

import { client } from "./client";

const job = await client.waitFor(
  {
    type: "datasetExport",
    exportId: "dex.019ffa5f-29a7-74de-a76c-7ba5ceedf37f",
  },
  { timeoutMs: 120_000, intervalMs: 2_000 },
);

if (job.status === "failed") {
  throw new Error(job.error?.message ?? "Export failed");
}

console.log(job.result.downloadUrl);

{
  "id": "dex.019ffa5f-29a7-74de-a76c-7ba5ceedf37f",
  "datasetId": "ds.019ffa5f-29a7-74de-a76c-7ba5ceedf37f",
  "status": "succeeded",
  "createdAt": "2026-11-04T10:00:00Z",
  "result": { "downloadUrl": "https://example.com/export.json" },
  "report": null,
  "error": null
}

Reference

TypeScript SDK

CLI

HTTP API

Parameters

Returns

Throws