Long-running jobs

Dataset uploads, exports, pipeline checks, pipeline runs, slices, splits, and field operations can continue after the initiating request returns. Use client.waitFor 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.

Wait for an export

Call datasets.startExport() using client.ts from the quickstart. Replace the dataset ID and field names with yours.

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, then wait for the job. Waiting without transferring the bytes and finalizing leaves the job pending. See the upload endpoint. Training Runs and Batch Inference Runs have their own states and no waitFor target. Read them with trainings.getRun and batchInference.getRun; see the client method index.

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.

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 })`
Export	`datasets.getExport({ exportId })`
Pipeline check	`checks.get({ checkRunId })`
Pipeline run	`runs.get({ runId })`
Slice	`datasets.getSlice({ sliceId })`
Split	`datasets.listFieldsPage({ datasetId, names: column })`
Field operations	`datasets.listAllFields({ datasetId })`

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

TypeScript SDK

Pipelines as code

CLI

Wait for an export

Choose a wait target

Handle failure and timeout

Poll yourself

​Wait for an export

​Choose a wait target

​Handle failure and timeout

​Poll yourself

Wait for an export

Choose a wait target

Handle failure and timeout

Poll yourself