---
title: Exports
description: Build and download dataset exports in COCO, YOLO, CVAT, Pascal VOC, LabelMe, CSV, or canonical Pictograph JSON.
section: API Reference
order: 8
---
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).

```python
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.

```python
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

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

## get

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

## download

Stream the ZIP to a local file (chunked).

```python
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`:

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

## delete

```python
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) |