client.exports

Bases: SyncResource

Sync exports namespace (client.exports).

create

create(project_id: UUID | str, version_id: UUID | str, *, format: ExportFormat | str, include_assets: bool = True, exclude_empty: bool = False, idempotency_key: str | None = None) -> Export

Request an export of a frozen version (async — returns a queued row).

Poll client.jobs.get(export.job_id) or re-list for status.

Parameters:

Name	Type	Description	Default
format	ExportFormat | str	bundle format — coco | yolo | delta.	required
include_assets	bool	bundle the source image files alongside the labels.	True
exclude_empty	bool	skip assets that carry no annotations.	False
idempotency_key	str | None	forces a distinct row even when the options match an existing export (the server otherwise dedups on options and returns the existing row). Omit to reuse a matching live export.	None

Raises:

Type	Description
NotFoundError	version not in this project (returned as a not-found).
ConflictError	the version is not ready yet (RESOURCE_NOT_READY).
ForbiddenError	caller is not a project manager (AUTH_FORBIDDEN).
UnprocessableError	invalid format value.

list

list(project_id: UUID | str, version_id: UUID | str, *, format: ExportFormat | str | None = None, status: ExportStatus | str | None = None, created_at_from: datetime | str | None = None, created_at_to: datetime | str | None = None, limit: int | None = None, cursor: str | None = None) -> Page[Export]

List a version's exports, newest first (cursor-paginated; iterate for all).

Parameters:

Name	Type	Description	Default
format	ExportFormat | str | None	filter to one bundle format (coco|yolo|delta).	None
status	ExportStatus | str | None	filter to one status (pending|queued|running|ready|failed|expired).	None

Raises:

Type	Description
ConflictError	version not yet ready (RESOURCE_NOT_READY).
NotFoundError	version not in this project.
BadRequestError	malformed cursor (INVALID_CURSOR).
UnprocessableError	invalid format / status enum value.

download_url

download_url(project_id: UUID | str, version_id: UUID | str, export_id: UUID | str) -> ExportDownloadUrl

Fresh presigned GET URL for a ready export bundle (re-signed per call).

Raises:

Type	Description
NotFoundError	version or export not found.
ForbiddenError	not the export creator and not a workspace admin (AUTH_FORBIDDEN).
ConflictError	the export is still building (RESOURCE_NOT_READY).
GoneError	the export has expired (EXPORT_EXPIRED) or failed (EXPORT_FAILED) — re-create it.

delete

delete(project_id: UUID | str, version_id: UUID | str, export_id: UUID | str) -> None

Force-delete an export row (204). Workspace admin only.

Raises:

Type	Description
NotFoundError	no such export on this version.
ForbiddenError	caller is not a workspace admin (AUTH_FORBIDDEN).

download_to

download_to(project_id: UUID | str, version_id: UUID | str, export_id: UUID | str, path: str | Path) -> Path

Download a ready export bundle to path (parent dirs created). Fetches a fresh presigned URL, then streams from S3 with an auth-less client. Returns the written path.

Raises:

Type	Description
NotFoundError / ForbiddenError / ConflictError / GoneError	as :meth:download_url (the URL is fetched first).

Response models

Models returned by client.exports methods (fields, types, and what each means).

Export domain models — a downloadable bundle of a frozen project version (ADR-0048).

An export is produced asynchronously: create returns a row in pending / queued and the worker fills in size_bytes / exported_count / result_details when it reaches a terminal status. Poll /jobs/{job_id} (via client.jobs.get(export.job_id)) for progress, or re-list the version's exports.

SkippedDetail

Bases: BaseModel

One annotation the bundler couldn't represent in the target format.

annotation_id is an int for COCO/YOLO bundles and a str for delta / manifest-miss sentinels — hence the int | str type.

Export

Bases: BaseModel

One export row (ADR-0048). Terminal statuses are ready / failed / expired; the count/size/result_details fields are null until terminal.

ExportDownloadUrl

Bases: BaseModel

Presigned HTTPS URL for a ready export bundle (1-hour TTL). Follow url with a plain GET — S3 validates expiry at request start, so the TTL covers an arbitrary-duration download.