datasets - Evolve

datasets() returns the catalog client. A ref is name or name@version.

list, get, getActive

TypeScript
Python

list(options?: { search?: string; limit?: number; cursor?: string }): DatasetList
get(
  ref: string,
  options?: { limit?: number; cursor?: string },
): Promise<Dataset>
getActive(
  name: string,
  options?: { limit?: number; cursor?: string },
): Promise<ActiveDataset>

The catalog, one dataset with one page of its tasks (default 200, at most 500), or the active version alone. getActive throws NoActiveVersionError when nothing is runnable. A task row carries public fields only; see Task.

const dataset = await datasets().get("terminal-bench-4@4.0");

def list(
    *,
    search: Optional[str] = None,
    limit: Optional[int] = None,
    cursor: Optional[str] = None,
)
async def get(
    ref: str,
    *,
    limit: Optional[int] = None,
    cursor: Optional[str] = None,
) -> Dataset
async def get_active(
    name: str,
    *,
    limit: Optional[int] = None,
    cursor: Optional[str] = None,
) -> ActiveDataset

The catalog, one dataset with one page of its tasks, or the active version alone. get_active raises NoActiveVersionError when nothing is runnable.

dataset = await datasets().get("terminal-bench-4@4.0")

getTaskBuild

TypeScript
Python

getTaskBuild(
  ref: string,
  taskName: string,
): Promise<TaskBuild>

One task’s build record: its outcome and, on failure, the failing step and log.

const build = await datasets().getTaskBuild("my-swe@1.0", "broken-task");

async def get_task_build(
    ref: str,
    task_name: str,
) -> TaskBuild

One task’s build record: its outcome and, on failure, the failing step and log.

build = await datasets().get_task_build("my-swe@1.0", "broken-task")

preflight

TypeScript
Python

preflight(input: { source: { directory: string } }): Promise<DatasetPreflight>

Dry-run a local folder of tasks: only each task’s metadata is sent, nothing is uploaded or written.

const verdict = await datasets().preflight({ source: { directory: "./my-swe" } });

async def preflight(
    *,
    directory: str,
) -> DatasetPreflight

Dry-run a local folder of tasks: only each task’s metadata is sent, nothing is uploaded or written.

verdict = await datasets().preflight(directory="./my-swe")

publish

TypeScript
Python

publish(input: { source: DatasetSource; name?: string; version?: string }, options?: { onUploadProgress?: (sentBytes: number, totalBytes: number) => void; onRegistered?: (importId: string) => void }): Promise<DatasetImport>

Publish a version from one source: { git_url, git_ref, git_path? } (an https:// URL, and a subfolder that exists at the ref), { directory }, { archive_url } or { hub_package }. Returns the import record; follow it with watchImport.onUploadProgress reports sent bytes for a directory source, and onRegistered fires once with the import id when a large upload begins. What is packed is on datasets.

const imp = await datasets().publish({
  source: { directory: "./my-swe" },
  name: "my-swe",
  version: "1.0",
});

async def publish(
    *,
    git_url=None,
    git_ref=None,
    git_path=None,
    directory=None,
    archive_url=None,
    hub_package=None,
    name=None,
    version=None,
    on_upload_progress=None,
    on_registered=None,
) -> DatasetImport

Publish a version from one source: git_url with git_ref (and git_path), directory, archive_url, or hub_package. Returns the import record; follow it with watch_import.

imp = await datasets().publish(
    directory="./my-swe",
    name="my-swe",
    version="1.0",
)

getImport, watchImport, listImports

TypeScript
Python

getImport(id: string): Promise<DatasetImport>
watchImport(id: string, options?: { onStatus?: (datasetImport: DatasetImport) => void; onProgress?: (progress: DatasetImportProgress, datasetImport: DatasetImport) => void; onVersion?: (version: DatasetVersion, dataset: Dataset) => void; signal?: AbortSignal; pollIntervalMs?: number; settleTimeoutMs?: number }): Promise<DatasetImport>
listImports(options?: { status?: DatasetImportStatus; dataset?: string; limit?: number; cursor?: string }): DatasetImportList

Read one publish, follow it until the version is READY or FAILED, or list your publishes. watchImport polls every pollIntervalMs (default 2000): onStatus fires on every status change, onProgress on every change of the five-phase progress (extracting, parsing, building, copying, verifying), onVersion on the version’s state. settleTimeoutMs (default 30 minutes) bounds the wait; past it the watch throws ImportSettleError with the last observed state. listImports filters by status and dataset.

const done = await datasets().watchImport(imp.id);

async def get_import(id: str) -> DatasetImport
async def watch_import(
    id: str,
    *,
    on_status=None,
    on_progress=None,
    on_version=None,
    poll_interval_s: float = 2.0,
    timeout_s: Optional[float] = None,
    settle_timeout_s: float = ...,
) -> DatasetImport
def list_imports(
    *,
    status: Optional[str] = None,
    dataset: Optional[str] = None,
    limit: Optional[int] = None,
    cursor: Optional[str] = None,
)

Read one publish, follow it until the version is READY or FAILED, or list your publishes. watch_import polls every poll_interval_s: on_status fires on every status change, on_progress on every change of the five-phase progress (extracting, parsing, building, copying, verifying), on_version on the version’s state. settle_timeout_s (default 30 minutes) bounds the wait; past it the watch raises ImportSettleError with the last observed state. list_imports filters by status and dataset.

done = await datasets().watch_import(imp.id)

download

TypeScript
Python

download(ref: string): Promise<Buffer>
download(
  ref: string,
  options: { to: string },
): Promise<string>
download(
  ref: string,
  options: { stream: true },
): Promise<ReadableStream<Uint8Array>>

The original package of a dataset you own: the bytes, the saved file’s path, or a stream. The Buffer and { to } shapes verify the download against the digest the server states and throw EvolveDigestMismatchError on a mismatch; { stream: true } is unverified. A version published before packages were retained answers package_not_retained. Prefer { to } for anything sizeable.

const path = await datasets().download(
  "my-swe@1.0",
  { to: "./corpora" },
);

async def download(
    ref: str,
    *,
    to: Optional[str] = None,
)

The original package of a dataset you own: the bytes, or with to the saved file’s path. Both shapes verify the download against the digest the server states, raising EvolveDigestMismatchError on a mismatch. A version published before packages were retained answers package_not_retained. Prefer to for anything sizeable.

path = await datasets().download(
    "my-swe@1.0",
    to="./corpora",
)

activate, update, delete

TypeScript
Python

activate(
  name: string,
  version: string,
): Promise<Dataset>
update(
  name: string,
  patch: { upstream_auto_import: boolean },
): Promise<Dataset>
delete(name: string): Promise<void>

Make a READY version the active one (version_not_ready while building, version_not_activatable for FAILED or ARCHIVED), switch automatic import of new upstream versions (upstream_not_watchable without a moving git ref), or delete a dataset you own (dataset_not_owned on a platform dataset, dataset_in_use naming the jobs that reference it).

await datasets().activate("my-swe", "1.0");

async def activate(
    name: str,
    version: str,
) -> Dataset
async def update(
    name: str,
    *,
    upstream_auto_import: bool,
) -> Dataset
async def delete(name: str) -> None

await datasets().activate("my-swe", "1.0")

​list, get, getActive

​getTaskBuild

​preflight

​publish

​getImport, watchImport, listImports

​download

​activate, update, delete