# aws s3api list-object-versions

AWS CLI commands · Updated 16 November 2026

**Short answer:** aws s3api list-object-versions --bucket my-bucket --prefix path/file.txt lists every stored version of matching objects, plus delete markers. To undelete a file in a versioned bucket, find its delete marker here and delete that marker by version ID; the previous version becomes current again.

## What the command does

In a bucket with versioning enabled (or suspended), every overwrite keeps the old copy and every plain delete adds a **delete marker** rather than removing data. `list-object-versions` shows all of it in two arrays:

- `Versions[]`: real object versions, each with `Key`, `VersionId`, `IsLatest`, `LastModified`, `Size` and `StorageClass`.
- `DeleteMarkers[]`: markers, with `Key`, `VersionId`, `IsLatest` and `LastModified`.

An object whose latest entry is a delete marker looks deleted to `GET` and `ls`, but all its data is still there and still billed.

## Syntax

```
aws s3api list-object-versions --bucket my-bucket \
  [--prefix path/] [--delimiter /] \
  [--key-marker ...] [--version-id-marker ...] \
  [--max-items 100] [--query ...]
```

`--prefix` is a prefix match, so `--prefix report.csv` also returns `report.csv.bak`. Filter on `Key` in `--query` when you need one exact key.

## Worked examples

**History of one file, newest first:**

```
aws s3api list-object-versions --bucket my-bucket --prefix config/app.yaml \
  --query "Versions[?Key=='config/app.yaml'].[VersionId,LastModified,Size,IsLatest]" \
  --output table
```

**Undelete a file** by removing the delete marker that is currently on top:

```
MARKER=$(aws s3api list-object-versions --bucket my-bucket --prefix config/app.yaml \
  --query "DeleteMarkers[?Key=='config/app.yaml' && IsLatest].VersionId | [0]" --output text)
aws s3api delete-object --bucket my-bucket --key config/app.yaml --version-id "$MARKER"
```

**Roll back to an older version** by copying it over the current one (keeps full history):

```
aws s3api copy-object --bucket my-bucket --key config/app.yaml \
  --copy-source "my-bucket/config/app.yaml?versionId=3HL4kqtJlcpXroDTDmJ.rmSpXd3dIbrHY"
```

**Every file that currently looks deleted under a prefix:**

```
aws s3api list-object-versions --bucket my-bucket --prefix uploads/ \
  --query "DeleteMarkers[?IsLatest].Key" --output json
```

**How much storage old versions are using** (JSON output so the sum covers all pages):

```
aws s3api list-object-versions --bucket my-bucket \
  --query "sum(Versions[?!IsLatest].Size)" --output json
```

## Reading the result

| You see | Meaning |
|---|---|
| `VersionId: "null"` | Object written before versioning was enabled, or while it was suspended. |
| Delete marker with `IsLatest: true` | The object appears deleted; older versions are recoverable. |
| Only a delete marker, no versions | An "expired object delete marker"; safe to remove, it hides nothing. |
| Many versions of small, frequently rewritten keys | A likely cost driver; add a noncurrent-version expiration rule. |

## Gotchas

- **Deleting a version ID is permanent.** `delete-object` with a real version ID (not a marker) destroys that version with no undo.
- **Per-page queries.** As with other paginated listings, `--output text` applies `--query` to each page of results, so prefer JSON for totals and sorting.
- **Buckets with versioning cannot be emptied with `aws s3 rm` alone**; versions and markers remain. See [deleting a versioned bucket](https://cloudconsole.dev/how-to/delete-s3-bucket-with-versioning).
- **MFA delete**, if enabled, requires the `--mfa` option for permanent version deletes.

## Questions

### How do I restore a deleted file in a versioned S3 bucket?

List versions for the key, find the delete marker with IsLatest true, and delete that marker with delete-object --version-id. The previous version becomes current.

### Why is my bucket larger than the objects I can see?

Noncurrent versions are billed like any other object. Sum Versions[?!IsLatest].Size to see how much they use, and add a lifecycle rule to expire them.

### What does VersionId null mean?

The object was stored when versioning was off or suspended. It is still a real version and can be addressed with the version ID null.

## When this happens away from your desk

Recovering an accidentally deleted file is a high-pressure job that is easy to get wrong. CloudConsole, a phone app for AWS, is built with production guardrails and to show resources and their recent changes on a phone.

[About the CloudConsole app](https://cloudconsole.dev/aws-console-app) · [Download on the App Store](https://apps.apple.com/app/cloudconsole-for-aws/id6835419710)

## Sources

- [AWS CLI Command Reference: s3api list-object-versions](https://docs.aws.amazon.com/cli/latest/reference/s3api/list-object-versions.html)
- [ListObjectVersions API reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListObjectVersions.html)

## Related

- [How to delete an S3 bucket with versioning enabled](https://cloudconsole.dev/how-to/delete-s3-bucket-with-versioning)
- [aws s3api delete-objects](https://cloudconsole.dev/cli/s3api-delete-objects)
- [aws s3api put-bucket-lifecycle-configuration](https://cloudconsole.dev/cli/s3api-put-bucket-lifecycle-configuration)
- [aws s3api list-objects-v2](https://cloudconsole.dev/cli/s3api-list-objects-v2)
- [BucketNotEmpty: The bucket you tried to delete is not empty](https://cloudconsole.dev/errors/s3-bucketnotempty)
- [aws s3api head-object](https://cloudconsole.dev/cli/s3api-head-object)

---

Source: https://cloudconsole.dev/cli/s3api-list-object-versions

CloudConsole is an independent iPhone and Android app for Amazon Web Services by Cloudconcur Ltd. It is not affiliated with Amazon Web Services.
