ListObjectVersions (GetBucketVersions)

Lists all object versions in a bucket, including delete markers.

Usage notes

ListObjectVersions (GetBucketVersions) returns all object versions, including delete markers. ListObjects (GetBucket) returns only current versions without delete markers.
When you call ListObjectVersions (GetBucketVersions), objects are returned in alphabetical order by name, and the versions of the same object are returned from the most recent to the earliest, regardless of the alphabetical order of the version IDs.
If logging and real-time log query are enabled for the bucket, the operation field in the generated log is GetBucket.
Calls to ListObjectVersions (GetBucketVersions) are billed by the number of PUT requests, as described in API operation calling fees.

Request syntax

GET /?versions HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

When you call this operation in OSS on Cloud Box, you need to replace the Host with the CloudBox endpoints. For more information, see CloudBox endpoints。

Request headers

DescribeRegions uses only common request headers. For more information, see Common request headers.

Request parameters

Use these parameters to filter results: prefix, key-marker, version-id-marker, delimiter, and max-keys.

Parameter	Type	Required	Example	Description
delimiter	String	No	/	The character used to group objects by name. If both prefix and delimiter are specified, the response contains CommonPrefixes. Objects whose names share the same string from the prefix to the next delimiter occurrence are grouped as a single CommonPrefixes entry. If prefix is a directory name and delimiter is a forward slash (/), only objects in that directory are returned. Subdirectory names appear in CommonPrefixes, but objects and directories within subdirectories are not listed. Default value: empty.
key-marker	String	Required if version-id-marker is specified.	example	Returns objects alphabetically after this value. Can be used with version-id-marker. Maximum length: 1,024 bytes. Default value: empty.
version-id-marker	String	No	CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****	Returns versions created before this marker for the object specified by key-marker, in descending order by creation time. If omitted, results start from the latest version of the object alphabetically after key-marker. Default value: empty. Valid values: version IDs.
max-keys	String	No	100	The maximum number of objects to return. If results exceed max-keys, the response includes `NextKeyMarker` and `NextVersionIdMarker` as pagination markers for the next request. Valid values: 1 to 999. Default value: 100.
prefix	String	No	fun	The prefix that the names of returned objects must contain. The value must be less than 1,024 bytes in length. When you use prefix to filter the results, the Key values in the response still include the prefix. If prefix is set to a directory name, all objects and subdirectories in that directory are listed. Default value: empty.
encoding-type	String	No	URL	The encoding type of the response content. Default value: empty. Valid values: URL. Important The values of delimiter, marker, prefix, NextMarker, and Key are UTF-8 encoded. If any of these values contain control characters that XML 1.0 does not support, set encoding-type to encode the Delimiter, Marker, Prefix, NextMarker, and Key values in the response.

Response parameters

Parameter	Type	Example	Description
ListVersionsResult	Container	N/A	Container for ListObjectVersions (GetBucketVersions) results. Child nodes: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, NextMarker, Version, and DeleteMarker Parent nodes: none
CommonPrefixes	Container	N/A	If delimiter is specified, objects whose names share the same string from the prefix to the next delimiter occurrence are grouped as a single CommonPrefixes entry. Parent nodes: ListVersionsResult
Delimiter	String	/	The character used to group objects by name. Objects sharing the same string from the prefix to the next delimiter occurrence are grouped as a single CommonPrefixes entry. Parent nodes: ListVersionsResult
EncodingType	String	URL	The encoding type of the response content. If encoding-type is specified in the request, the values of Delimiter, Marker, Prefix, NextMarker, and Key are encoded. Parent nodes: ListVersionsResult
IsTruncated	String	true	Indicates whether the results are truncated. true: not all results are returned. false: all results are returned. Valid values: true and false. Parent nodes: ListVersionsResult
KeyMarker	String	example	The object from which listing starts. Parent nodes: ListVersionsResult
VersionIdMarker	String	CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****	The version from which the ListObjectVersions (GetBucketVersions) operation starts. Used with KeyMarker. Parent nodes: ListVersionsResult
NextKeyMarker	String	test	Included when results are truncated. Use as key-marker in the next request to continue listing. Parent nodes: ListVersionsResult
NextVersionIdMarker	String	CAEQGBiBgIC_jq7P9xYiIDRiZWJkNjY2Y2Q4NDQ5ZTI5ZGE5ODIxMTIyZThl****	Included when results are truncated. Use as version-id-marker in the next request to continue listing. Parent nodes: ListVersionsResult
MaxKeys	String	1000	The maximum number of objects returned in the response. Parent nodes: ListVersionsResult
Name	String	examplebucket-1250000000	The name of the bucket. Parent nodes: ListVersionsResult
Prefix	String	fun	The prefix that must be included in the names of the listed objects. Parent nodes: ListVersionsResult
Version	Container	N/A	Container for object versions, excluding delete markers. Parent nodes: ListVersionsResult
DeleteMarker	Container	N/A	Container for delete markers. Parent nodes: ListVersionsResult
ETag	String	250F8A0AE989679A22926A875F0A2****	The ETag of the object, used to identify object content. For objects created by PutObject, the ETag is the MD5 hash of the content. For objects created by other methods, the ETag is a unique value calculated by a different rule, not the MD5 hash. Note The ETag value indicates only whether the content of the object has changed. Do not use the ETag value as the MD5 hash of the object content to verify data integrity. Parent nodes: ListVersionsResult.Version
Key	String	example	The name of the object. Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker
LastModified	Time	2019-04-09T07:27:28.000Z	The time when the object was last modified. The minimum storage duration for objects in the Infrequent Access storage class is 30 days. The duration is calculated from the Last-Modified time of the object. If you delete an object more than 30 days after its Last-Modified time, no early deletion fee is charged. The minimum storage duration for objects in the Archive storage class is 60 days. The duration is calculated from the Last-Modified time of the object. If you delete an object more than 60 days after its Last-Modified time, no early deletion fee is charged. Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker
TransitionTime	Time	2024-04-23T07:21:42.000Z	The time when the object storage class is changed to Cold Archive or Deep Cold Archive based on lifecycle rules. If you delete a Cold Archive or Deep Cold Archive object more than 180 days after it is converted, no early deletion fee is charged. If you delete the object within 180 days after it is converted, an early deletion fee is charged. This field cannot be used to determine the time when an object is converted to the IA or Archive storage class by a lifecycle rule. Whether an IA or Archive object meets the minimum storage duration requirement depends on the `Last-Modified` time. Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker
VersionId	String	CAEQMxiBgMDNoP2D0BYiIDE3MWUxNzgxZDQxNTRiODI5OGYwZGMwNGY3MzZjN****	The version ID of the object. Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker
IsLatest	String	true	Whether this version is the current version. Valid values: true: The object version is the current version. false: The object version is not the current version. Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker
Size	String	93731	The object size in bytes. Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker
StorageClass	String	Standard	The storage class of the object. Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker
Owner	Container	N/A	Container for bucket owner information. Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker
DisplayName	String	12345125285864390	The name of the object owner. Parent nodes: ListVersionsResult.Version.Owner and ListVersionsResult.DeleteMarker.Owner
ID	String	1234512528586****	The user ID of the bucket owner. Parent nodes: ListVersionsResult.Version.Owner and ListVersionsResult.DeleteMarker.Owner
RestoreInfo	String	ongoing-request="true"	The restored state of the object. Not included if no RestoreObject requests are sent or the requests expire. While the object is being restored, the value is `ongoing-request="true"`. After the object is restored, the value is in the format `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"`, where `expiry-date` indicates the time before which the restored object can be read.

For more information about the common response headers, such as x-oss-request-id and Content-Type in the response to a ListObjectVersions (GetBucketVersions) request, see Common response headers.

Examples

List the versions of objects in an unversioned bucket

Sample requests

GET /?versions HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 07:27:48 GMT
Authorization: OSS qn6q**************:77Dv****************

Sample success response

HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 1262
Connection: keep-alive
Date: Thu, Tue, 09 Apr 2019 07:27:48 GMT
Server: AliyunOSS
x-oss-request-id: 534B371674E88A4D8906****

<ListVersionsResult>
    <Name>examplebucket-1250000000</Name>
    <Prefix/>
    <KeyMarker/>
    <VersionIdMarker/>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Version>
        <Key>example-object-1.jpg</Key>
        <VersionId/>
        <IsLatest>true</IsLatest>
        <LastModified>2019-08-5T12:03:10.000Z</LastModified>    
        <ETag>5B3C1A2E053D763E1B669CC607C5A0FE1****</ETag>
        <Size>20</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1250000000</ID>
            <DisplayName>1250000000</DisplayName>
        </Owner>
        <TransitionTime>2024-04-23T07:21:42.000Z</TransitionTime>
    </Version>
    <Version>
        <Key>example-object-2.jpg</Key>
        <VersionId/>
        <IsLatest>true</IsLatest>
        <LastModified>2019-08-9T12:03:09.000Z</LastModified>
        <ETag>5B3C1A2E053D763E1B002CC607C5A0FE1****</ETag>
        <Size>20</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1250000000</ID>
            <DisplayName>1250000000</DisplayName>
        </Owner>
    </Version>
    <Version>
        <Key>example-object-3.jpg</Key>
        <VersionId/>
        <IsLatest>true</IsLatest>
        <LastModified>2019-08-10T12:03:08.000Z</LastModified>
        <ETag>4B3F1A2E053D763E1B002CC607C5AGTRF****</ETag>
        <Size>20</Size>
        <StorageClass>STANDARD</StorageClass>
        <Owner>
            <ID>1250000000</ID>
            <DisplayName>1250000000</DisplayName>
        </Owner>
    </Version>
</ListVersionsResult>

List the versions of objects in a versioning-enabled bucket

Bucket oss-example contains two objects: example with three versions (111222, 000123 as a delete marker, and 222333, in descending order by creation time), and pic.jpg with one version (232323).

If you set key-marker to example and version-id-marker to 111222, the following three versions are returned in sequence: 000123 of example, 222333 of example, and 232323 of pic.jpg.

Sample requests

GET /?versions&key-marker=example&version-id-marker=CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1**** HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 07:27:48 GMT
Authorization: OSS qn6q**************:77Dv****************

Sample success responses

HTTP/1.1 200 OK
x-oss-request-id: 5CAC4974B7AEADE01700****
Date: Tue, 09 Apr 2019 07:27:48 GMT
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListVersionsResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
    <Name>oss-example</Name>
    <Prefix></Prefix>
    <KeyMarker>example</KeyMarker>
    <VersionIdMarker>CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****</VersionIdMarker>
    <MaxKeys>100</MaxKeys>
    <Delimiter></Delimiter>
    <IsTruncated>false</IsTruncated>
    <DeleteMarker>
        <Key>example</Key>
        <VersionId>CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****</VersionId>
        <IsLatest>false</IsLatest>
        <LastModified>2019-04-09T07:27:28.000Z</LastModified>
        <Owner>
          <ID>1234512528586****</ID>
          <DisplayName>12345125285864390</DisplayName>
        </Owner>
    </DeleteMarker>
    <Version>
        <Key>example</Key>
        <VersionId>CAEQMxiBgMDNoP2D0BYiIDE3MWUxNzgxZDQxNTRiODI5OGYwZGMwNGY3MzZjN****</VersionId>
        <IsLatest>false</IsLatest>
        <LastModified>2019-04-09T07:27:28.000Z</LastModified>
        <ETag>"250F8A0AE989679A22926A875F0A2****"</ETag>
        <Type>Normal</Type>
        <Size>93731</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>1234512528586****</ID>
          <DisplayName>12345125285864390</DisplayName>
        </Owner>
    </Version>
    <Version>
        <Key>pic.jpg</Key>
        <VersionId>CAEQMxiBgMCZov2D0BYiIDY4MDllOTc2YmY5MjQxMzdiOGI3OTlhNTU0ODIx****</VersionId>
        <IsLatest>true</IsLatest>
        <LastModified>2019-04-09T07:27:28.000Z</LastModified>
        <ETag>"3663F7B0B9D3153F884C821E7CF4****"</ETag>
        <Type>Normal</Type>
        <Size>574768</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>1234512528586****</ID>
          <DisplayName>12345125285864390</DisplayName>
        </Owner>
    </Version>
</ListVersionsResult>

Archive objects and Cold Archive objects stored in the requested bucket

Assume that the examplebucket bucket contains the exampleobject1.txt, exampleobject2.txt, and exampleobject3.txt objects. All three objects are in the Cold Archive storage class. The states of the three objects are as follows:

For exampleobject1.txt, a RestoreObject request has not been submitted, or the submitted RestoreObject request has expired.
For exampleobject2.txt, a RestoreObject request has been submitted, and the restore operation is in progress.
For exampleobject3.txt, a RestoreObject request has been submitted and the restore operation is complete.

Sample request

GET / HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 5CAC4974B7AEADE01700****
Date: Tue, 09 Apr 2019 07:27:48 GMT
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListVersionsResult xmlns="http://doc.oss-cn-hangzhou.aliyuncs.com">
    <Name>oss-example</Name>
    <Prefix></Prefix>
    <KeyMarker>example</KeyMarker>
    <VersionIdMarker>CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****</VersionIdMarker>
    <MaxKeys>100</MaxKeys>
    <Delimiter></Delimiter>
    <IsTruncated>false</IsTruncated>
    <Version>
        <Key>exampleobject1.txt</Key>
        <VersionId>CAEQMxiBgICAof2D0BYiIDJhMGE3N2M1YTI1NDQzOGY5NTkyNTI3MGYyMzJm****</VersionId>
        <IsLatest>false</IsLatest>
        <LastModified>2019-04-09T07:27:28.000Z</LastModified>
        <Owner>
          <ID>1234512528586****</ID>
          <DisplayName>12345125285864390</DisplayName>
        </Owner>
     </Version>
    <Version>
        <Key>exampleobject2.txt</Key>
        <VersionId>CAEQMxiBgMDNoP2D0BYiIDE3MWUxNzgxZDQxNTRiODI5OGYwZGMwNGY3MzZjN****</VersionId>
        <IsLatest>false</IsLatest>
        <LastModified>2019-04-09T07:27:28.000Z</LastModified>
        <ETag>"250F8A0AE989679A22926A875F0A2****"</ETag>
        <Type>Normal</Type>
        <Size>93731</Size>
        <StorageClass>Standard</StorageClass>
        <RestoreInfo>ongoing-request="true"</RestoreInfo>
        <Owner>
          <ID>1234512528586****</ID>
          <DisplayName>12345125285864390</DisplayName>
        </Owner>
     </Version>
    <Version>
        <Key>exampleobject3.txt</Key>
        <VersionId>CAEQMxiBgMCZov2D0BYiIDY4MDllOTc2YmY5MjQxMzdiOGI3OTlhNTU0ODIx****</VersionId>
        <IsLatest>true</IsLatest>
        <LastModified>2019-04-09T07:27:28.000Z</LastModified>
        <ETag>"3663F7B0B9D3153F884C821E7CF4****"</ETag>
        <Type>Normal</Type>
        <Size>574768</Size>
        <StorageClass>Standard</StorageClass>
        <RestoreInfo>ongoing-request="false", expiry-date="Thr, 24 Mon 2020 12:40:33 GMT"</RestoreInfo>
        <Owner>
          <ID>1234512528586****</ID>
          <DisplayName>12345125285864390</DisplayName>
        </Owner>
     </Version>
</ListVersionsResult>

OSS SDKs

Call this operation with the following OSS SDKs:

ossutil command line interface

For information about the ossutil command that corresponds to the ListObjectVersions operation, see list-object-versions.

Error codes

Error code	HTTP status code	Description
NoSuchBucket	404	The bucket does not exist. Verify that the bucket name follows naming conventions.
AccessDenied	403	Only the bucket owner or RAM users with the `oss:ListObjectVersions` permission can call this operation.
InvalidArgument	400	The value of max-keys is less than 0 or greater than 1,000. The length of the prefix, marker, or delimiter parameter is invalid.