How to Retrieve a Specific Version of an S3 Object

S3-compatible object storage. Supports versioning, which means that it can store multiple versions of the same object. It’s a feature called Versioning in DigitalOcean Spaces, which lets you save old versions of a file when overwritten or deleted.

If you want to retrieve an object at a specific version, you can specify the object key and version ID. This is useful if you want to get to an old file, restore overwritten content or download an older version to check out.

Prerequisites

Before you get a particular version of an object, check the following:

Note: Versioning does not restore previous versions of files that were overwritten or deleted before versioning was turned on.

Step 1: Enable Object Versioning

See official guide: Spaces Versioning Config .

Refer to the official guide: Configure Spaces Versioning.

When versioning is enabled, to create additional versions of that object, you can upload the object again (overwriting it). When you delete an object, it might put a delete marker on it, but it does not actually delete the previous versions of the object.

Step 2: Find the Object's Version ID

And you need the version ID to get a specific version.

You can list object versions using an S3-compatible SDK or CLI. For example, with the AWS CLI:

aws s3api list-object-versions \
  --bucket YOUR_BUCKET_NAME \
  --prefix path/to/your-file.pdf \
  --endpoint-url https://YOUR_REGION.digitaloceanspaces.com

Replace YOUR_BUCKET_NAME, YOUR_REGION, and the object path with your actual values.

Check the output of Versions and pick which version you want If the prefix returns more than one file, ensure that the key and version ID of the object are an exact match.

Step 3: Retrieve the Specific Version

If you know the version id of the correct version you can get it using the get-object operation.

aws s3api get-object \
  --bucket YOUR_BUCKET_NAME \
  --key path/to/your-file.pdf \
  --version-id "YOUR_VERSION_ID" \
  --endpoint-url https://YOUR_REGION.digitaloceanspaces.com \
  downloaded-file.pdf

Replace YOUR_VERSION_ID with the version ID returned in the previous step. The last parameter is the name of the local file that the retrieved version will be written to.

This command fetches the specified version without overwriting the current object in the bucket.

Step 4: Verify the Retrieved File

After the download has finished:

  1. Check that the command completed successfully.

  2. Confirm that the downloaded file exists at the specified location.

  3. Open the file or compare its contents with the expected version.

  4. If necessary, inspect the object's metadata using the appropriate S3 API operation.

Important Considerations

Troubleshooting

No version ID is available: Confirm that versioning is enabled and that the object has been uploaded or modified since versioning was enabled.

Access denied: Check the credentials, bucket permissions, and permissions required to list or retrieve object versions.

The version cannot be found: Verify the bucket name, endpoint, object key, and version ID. Also confirm that the requested version has not been permanently deleted.

The command fails to connect: Ensure that the endpoint matches the bucket's DigitalOcean Spaces region and that the CLI credentials are configured correctly.

Additional Resources