# Empty a bucket

Delete every object, every older version and every delete marker of a bucket for good, in the background, and keep the bucket and its settings.

Emptying a bucket is the step before [deleting it](delete-a-bucket.md). Replace _example-uploads_
with your bucket's name.

**Warning:**
What is emptied is gone for good. Versioning cannot bring any of it back.

## Prerequisites

- Permission for `s3:ListBucketVersions` on the bucket (to count and to follow the job) and
  `s3:DeleteObjectVersion` on its objects (to start and to stop it). Without them, **Empty
  bucket** is unavailable and says "Needs s3:ListBucketVersions and s3:DeleteObjectVersion in
  this bucket."
- In the console, also `s3:GetBucket` on the bucket to open it (without it the bucket's page says
  "Access denied").
- The bucket is not one the platform writes (a database's backups, a Kafka cluster's tiered
  storage): those are emptied together with their database or cluster.

## Empty the bucket

**Console**
1. Open **Object Storage**, then open the bucket.
2. In the **⋯** menu, choose **Empty bucket**. The dialog counts what the bucket holds, for example
   "41 objects (12 MB), 30 older versions and 2 delete markers"; it counts at most 10,000 entries,
   and above that it says "at least". An empty bucket shows "_name_ is empty already."
3. Enter the bucket's name to confirm, then choose **Delete _N_ entries for good** (**Delete
   _N_+ entries for good** when the count stopped at 10,000).

A banner on every tab of the bucket shows how many entries are deleted and how many a second. You
can leave the page. To stop, choose **Stop** in the banner.

**CLI**
```sh
dcloud s3 bucket-objects count example-uploads
dcloud s3 bucket-objects empty example-uploads
dcloud s3 bucket-objects empty-status example-uploads
```

To stop: `dcloud s3 bucket-objects empty-cancel example-uploads`.

**API**
```http
POST /s3/api/buckets/example-uploads/empty
```

The answer is `202` with the new job, or `200` with the one already running. Follow it with
`GET /s3/api/buckets/example-uploads/empty`, and stop it with
`POST /s3/api/buckets/example-uploads/empty/cancel`.

## Result

The job reports `status` (`queued`, `running`, `done`, `failed` or `cancelled`), `total` (what
the bucket held when it started), `deleted`, `failed`, `perSecond` and, once it finished,
`remaining`. The bucket itself and its settings stay.

- Each version is still checked against your policies and the bucket policy. What they keep is
  counted in `failed` and stays; the banner then says "N entries still listed: your policies keep
  them, or storage did not let go of them yet." with **Empty again**.
- After **Stop**, what was deleted stays deleted; **Empty again** deletes the rest.
- 409 `Nothing is emptying this bucket` answers a cancel when no job runs.
- 400 `This bucket is managed by the platform; it is emptied with its resource.` for a bucket the
  platform writes.

## Delete one folder

To delete everything under one prefix instead of the whole bucket, choose **Delete folder** in the
folder's menu on **Objects** (see [Delete objects and folders](delete-objects.md)), or call
`delete-prefix`:

**Console**
On the bucket's **Objects** tab, in the folder's menu, choose **Delete folder**.

**CLI**
`dcloud s3 bucket-objects delete-prefix example-uploads --prefix photos/ --no-all-versions`
deletes the current objects under `photos/`; `--all-versions` deletes every version too.

**API**
```http
POST /s3/api/buckets/example-uploads/objects/delete-prefix
{ "prefix": "photos/", "allVersions": false }
```

Each call works for about 20 seconds and answers `{ deleted, failed, errors, done, cursor }`.
While `done` is `false`, call again with the `cursor` it returned. `allVersions: true` also deletes
every version and delete marker under the prefix for good and needs `s3:DeleteObjectVersion`;
`false` deletes the current objects, which a versioned bucket keeps as older versions. With prefix
`""` and `allVersions: true` it empties the bucket.

## With an S3 client

`aws s3 rm s3://example-uploads --recursive` removes the current objects. Older versions and delete
markers need `aws s3api delete-objects` with their `VersionId`s, which needs
`s3:DeleteObjectVersion`.

## Related

- [Delete a bucket](delete-a-bucket.md)
- `s3.bucket-objects.empty` · `dcloud s3 bucket-objects empty` · `s3.bucket-objects.delete-prefix`
