Exports

An export is a ZIP of an annotated dataset in a chosen format, optionally embedding the original image files. Export builds run server-side (a few seconds for hundreds of images, longer for tens of thousands).

from pictograph import Client
client = Client()

Formats

format	Notes
pictograph (default)	Canonical Pictograph JSON — the wire format the SDK consumes
coco	COCO instance segmentation / object detection
yolo	YOLO darknet .txt files (one per image)
cvat	CVAT XML
pascal_voc	Pascal VOC XML (one per image)
labelme	LabelMe JSON (one per image)
csv	Flat CSV — bbox annotations only

create

Build a new export. Defaults to wait=True, which blocks until the ZIP is ready.

export = client.exports.create(
    "my-dataset",
    "for-yolov8",
    format="yolo",
    include_images=True,
    class_filter=["car", "truck"],   # None = all classes
    status_filter="complete",        # "all" / "complete" / "in_progress" / "new"
    wait=True,
    poll_interval=2.0,
    timeout=600.0,
)
print(export.id, export.status, export.image_count, export.annotation_count)

Arg	Type	Default	Notes
dataset_name	str	required
name	str	required	Unique within the dataset
format	ExportFormat	"pictograph"	See table above
include_images	bool	True	When False, ZIP contains only annotations
class_filter	list[str] | None	None	Limit to these class names
status_filter	str	"complete"	Image status filter
wait	bool	True	Block until terminal status

wait=False returns a pending / processing Export. Poll via get or wait_for_completion.

list / iter

exports = client.exports.list(limit=20)
for e in client.exports.iter(page_size=50):
    print(e.dataset_name, e.name, e.status)

get

export = client.exports.get("my-dataset", "for-yolov8")
print(export.status, export.download_url)

download

Stream the ZIP to a local file (chunked).

from pathlib import Path

client.exports.download(
    "my-dataset", "for-yolov8",
    output_path=Path("./my-dataset.zip"),
)

The download URL is a signed URL valid for 60 minutes — generated fresh on every call.

wait_for_completion

If you used wait=False:

export = client.exports.create("ds", "name", format="coco", wait=False)
# … later
export = client.exports.wait_for_completion("ds", "name", timeout=300.0)

delete

client.exports.delete("my-dataset", "for-yolov8")

Removes the export and the stored ZIP. Other ongoing downloads of the same export will fail mid-stream.

Class filtering

class_filter only includes annotations matching the given class names. Images with no surviving annotations are still included if their status matches status_filter — they get an empty annotation list. Pass class_filter=None (default) to keep every annotation.

Common errors

Status	Exception	Cause
404	NotFoundError	Dataset or export missing
409	ConflictError	Export name already exists in this dataset
422	ValidationError	Unknown format or status_filter
408	PollTimeoutError	wait=True timed out (export keeps building)