# Upload a Dataset Zip

Upload a dataset as a single zip archive (up to 2 GB, 10,000 files) using an async task. Unlike the standard image upload endpoint, you do not hold an HTTP connection open while the zip is processed. The API returns a signed URL that you PUT the zip to, and a `taskId` you poll for status.

This endpoint accepts zips containing images and annotations in any of the formats supported by the Roboflow dataset upload tools (COCO, YOLO, Pascal VOC, etc.). Folder names are used as class labels for classification datasets.

## Flow

1. `POST /:workspace/:project/upload/zip` returns a signed URL and a `taskId`.
2. `PUT` the zip directly to the signed URL.
3. `GET /:workspace/upload/zip/:taskId` to poll until the task completes.

## Initiate the Upload

Send a `POST` to `/:workspace/:project/upload/zip`. The response includes a GCS signed URL and a `taskId`.

```bash
curl -X POST "https://api.roboflow.com/my-workspace/my-project/upload/zip?api_key=$ROBOFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"split": "train", "batchName": "my-batch"}'
```

### Body Parameters

```
- split (string, optional) - One of train, valid, or test. Defaults to train.
- batchName (string, optional) - Group uploaded images under a batch with this name.
```

### Response

```json
{
    "taskId": "abc123",
    "signedUrl": "https://storage.googleapis.com/...",
    "url": "https://api.roboflow.com/my-workspace/upload/zip/abc123"
}
```

## Upload the Zip

`PUT` the zip file to the returned `signedUrl`. The Content-Type must be `application/zip`.

```bash
curl -X PUT "$SIGNED_URL" \
  -H "Content-Type: application/zip" \
  --upload-file ./my-dataset.zip
```

Processing starts automatically once the upload completes.

## Poll Task Status

Send a `GET` to `/:workspace/upload/zip/:taskId`.

```bash
curl "https://api.roboflow.com/my-workspace/upload/zip/abc123?api_key=$ROBOFLOW_API_KEY"
```

The response follows the standard [Async Tasks](/developer/rest-api/async-tasks.md) shape. When the task completes, `result` includes a per-image summary plus any warnings or errors encountered during parsing.

```json
{
    "taskId": "abc123",
    "status": "completed",
    "progress": { "current": 250, "total": 250 },
    "result": {
        "uploaded": 248,
        "failed": 2,
        "warnings": [],
        "errors": []
    }
}
```

Up to 100 per-image errors and 100 warnings are reported. Videos and PDFs inside the zip are surfaced as unsupported-format warnings and skipped.

## Limits

* Maximum zip size: 2 GB
* Maximum files per zip: 10,000

## Errors

```
- 400 - The zip is malformed or exceeds the size or file count limits.
- 401 - Missing or invalid API key.
- 404 - The workspace, project, or task does not exist, or belongs to another workspace.
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roboflow.com/developer/rest-api/manage-images/upload-a-dataset-zip.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.