> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload local files

> Upload images, video, point clouds, or MCAP files from your machine to a new Avala dataset.

There are two ways to upload local files into Avala: the **Add Dataset wizard** in the web app (drag-and-drop) and the **`avala datasets upload`** CLI command. Both write to the same managed storage, both enforce the same per-user **10 GB** cap, and both create a normal Avala dataset that you can label, share, and export.

Use the wizard for ad-hoc uploads of a few hundred files. Use the CLI when you have many files, large files, or want to script the upload.

## Storage cap

Local uploads count against a **10 GB per-user** quota. Each individual file is capped at **2 GB**. Files larger than 2 GB are not currently supported via either the wizard or the CLI — split them, or use one of the cloud-storage data sources instead.

You can see your current usage on the local-upload step of the Add Dataset wizard, or fetch it from the API:

```bash theme={null}
curl https://api.avala.ai/api/v1/datasets/manual-upload/quota/ \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"
# {"used": 1342177280, "limit": 10737418240}
```

If you need a higher cap, contact [support@avala.ai](mailto:support@avala.ai).

## Web wizard (drag-and-drop)

1. Open Mission Control and click **Add Dataset**.
2. **Step 1 — Common data:** name the dataset, pick the data type (image, video, lidar, splat including `.4dgs`, MCAP, etc.), and set labels.
3. **Step 2 — Source:** pick **Local files**.
4. **Step 3 — Upload:** drag files into the drop zone or click to browse. The picker accepts only file types that match the data type from step 1 — for example, a Lidar dataset accepts `.pcd`, `.bin`, `.las`, `.laz`, `.ply` and rejects everything else with an inline reason. Per-file progress shows on each row.
5. Click **Submit** once **every** selected file has finished uploading. (The wizard keeps the button disabled while any file is still pending, uploading, or failed — partial batches would create a dataset with only some of the files you picked.) The dataset is created in your account immediately and is ready to label.

If a file fails (e.g. network blip), use the **Retry** button on the row. The wizard never re-uploads files that already succeeded.

## CLI (`avala datasets upload`)

Install the SDK:

```bash theme={null}
pip install avala
```

Authenticate by setting an API key (create one in **Settings → API Keys**):

```bash theme={null}
export AVALA_API_KEY=avk_...
```

Then run the upload — the CLI creates the dataset and uploads all files in one shot:

```bash theme={null}
avala datasets upload \
  --source ./recordings/2026-04-26/ \
  --name "PCD recordings 2026-04-26" \
  --slug pcd-recordings-2026-04-26 \
  --data-type lidar
```

The CLI walks the source directory, opens parallel connections to S3, and shows a progress bar. If a single upload fails the command stops with a non-zero exit code; rerun the command to retry.

### Common flags

| Flag                 | What it does                                                  |
| -------------------- | ------------------------------------------------------------- |
| `--source <path>`    | Local file or directory containing files to upload. Required. |
| `--name <name>`      | Display name for the new dataset. Required.                   |
| `--slug <slug>`      | URL-friendly identifier for the dataset. Required.            |
| `--data-type <type>` | One of `image`, `video`, `lidar`, `splat`, `mcap`. Required.  |
| `--visibility <vis>` | `private` (default) or `public`.                              |
| `--dry-run`          | List files that would upload, with their sizes, and exit.     |
| `--workers N`        | Parallel uploads (default 8).                                 |

### Quota errors

If your upload would push you over 10 GB, the API returns HTTP 413 and the CLI prints:

```
ERROR: Storage quota exceeded.
Used: 9.7 GB / 10 GB.
This upload would add 600 MB.
Free up space at https://avala.ai/@<org>/datasets, or contact support to raise the cap.
```

The CLI stops before issuing any further presigned URLs, so partial uploads are bounded.

## After the upload

Either path produces a normal dataset. From there you can:

* Define a [project](/docs/getting-started/concepts#project) over it and assign annotation tasks.
* Trigger an [export](/docs/sdks/rest-api#exports) once labelling is done.
* Browse items via `client.datasets.get(<uid>).items()` in the Python SDK.

Your files live in Avala-managed storage. Your dataset's [`provider_config`](/docs/sdks/rest-api#dataset-provider-config) handles access, so you don't need separate AWS credentials to view them.