Call ListObjectVersions (GetBucketVersions) to list the versions of all objects in a bucket, including delete markers - Object Storage Service

Lists the versions of all objects in a bucket, including delete markers.

Usage notes

When you call the ListObjectVersions (GetBucketVersions) operation, all versions of objects in the bucket are returned, including delete markers. When you call the ListObjects (GetBucket) operation, the current versions of objects in the bucket are returned, excluding delete markers.
When you call the ListObjectVersions (GetBucketVersions) operation, objects are returned in alphabetic order, but the versions of each object are returned by creation time in descending order.
If you enable logging and real-time log query for the bucket for which you call the ListObjectVersions (GetBucketVersions) operation, the value of the operation field in the log generated by calling the operation is GetBucket.
You are charged based on the number of PUT requests when you call the ListObjectVersions (GetBucketVersions) operation. For more information, see API operation calling fees.

Request structure

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

Request headers

All headers in a DescribeRegions request are common request headers. For more information, see Common request headers.

Request parameters

When you call the GetBucketVersions (ListObjectVersions) operation, you can specify the following parameters to filter the returned results: prefix, key-marker, version-id-marker, delimiter, and max-keys.

Parameter	Type	Required	Example	Description
delimiter	String	No	/	The character that you want to use to group objects by name. If you specify prefix and delimiter in the request, the response contains CommonPrefixes. The objects whose name contains the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes. If you set prefix to a directory name and delimiter to a forward slash (/), only objects in the directory are returned. The names of the subdirectories within the directory are returned in the CommonPrefixes element. However, objects and directories in the subdirectories are not listed. By default, this parameter is left empty.
key-marker	String	The key-marker parameter is required if the version-id-marker parameter is specified.	example	Specifies that objects whose names are alphabetically after the value of the key-marker parameter are returned. This parameter can be specified together with version-id-marker. The value of key-marker must be less than 1,024 bytes in length. By default, this parameter is left empty.
version-id-marker	String	No	CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****	Specifies that the versions created before the version specified by version-id-marker for the object whose name is specified by key-marker are returned by creation time in descending order. By default, if this parameter is not specified, the results are returned from the latest version of the object whose name is alphabetically greater than the key-marker value. By default, this parameter is left empty. Valid values: version IDs.
max-keys	String	No	100	The maximum number of objects to return. If the number of returned objects exceeds the value of the max-keys parameter, the response contains the `NextKeyMarker` and `NextVersionIdMarker` parameters as the markers for the next ListObjectVersions (GetBucketVersions) request. The `NextKeyMarker` and `NextVersionIdMarker` values are included in the response. Valid values: 1 to 999. Default value: 100.
prefix	String	No	fun	The prefix that the names of returned objects must contain. The value of prefix must be less than 1,024 bytes in length. If you specify a prefix in the request, the names of the returned objects contain the prefix. If you set prefix to a directory name in the request, the objects whose names contain the prefix are listed, including all objects and subdirectories in the directory. By default, this parameter is left empty.
encoding-type	String	No	URL	The encoding type of the content in the response. By default, this parameter is left empty. Valid value: URL. Important The values of delimiter, marker, prefix, NextMarker, and Key are UTF-8 encoded. If the value of delimiter, marker, prefix, NextMarker, or Key contains a control character that is not supported by the XML 1.0 standard, you can specify the encoding-type parameter to encode the value in the response.

Response parameters

Parameter	Type	Example	Description
ListVersionsResult	Container	N/A	The container that stores the results of the ListObjectVersions (GetBucketVersions) operation. Child nodes: Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, NextMarker, Version, and DeleteMarker Parent nodes: none
CommonPrefixes	String	N/A	Indicates that if the delimiter parameter is specified in the request, the response contains the CommonPrefixes parameter. Objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in CommonPrefixes. Parent nodes: ListVersionsResult
Delimiter	String	/	The character that is used to group objects by name. The objects whose names contain the same string from the prefix to the next occurrence of the delimiter are grouped as a single result element in the CommonPrefixes parameter. Parent nodes: ListVersionsResult
EncodingType	String	URL	The encoding type of the content in the response. If you specify encoding-type in the request, the values of Delimiter, Marker, Prefix, NextMarker, and Key are encoded in the response. Parent nodes: ListVersionsResult
IsTruncated	String	true	Indicates whether the returned results are truncated. true: indicates that not all results are returned for the request. false: indicates that all results are returned for the request. Valid values: true and false. Parent nodes: ListVersionsResult
KeyMarker	String	example	Indicates the object from which the ListObjectVersions (GetBucketVersions) operation starts. Parent nodes: ListVersionsResult
VersionIdMarker	String	CAEQMxiBgICbof2D0BYiIGRhZjgwMzJiMjA3MjQ0ODE5MWYxZDYwMzJlZjU1****	The version from which the ListObjectVersions (GetBucketVersions) operation starts. This parameter is used together with KeyMarker. Parent nodes: ListVersionsResult
NextKeyMarker	String	test	If not all results are returned for the request, the NextKeyMarker parameter is included in the response to indicate the key-marker value of the next ListObjectVersions (GetBucketVersions) request. Parent nodes: ListVersionsResult
NextVersionIdMarker	String	CAEQGBiBgIC_jq7P9xYiIDRiZWJkNjY2Y2Q4NDQ5ZTI5ZGE5ODIxMTIyZThl****	If not all results are returned for the request, the NextVersionIdMarker parameter is included in the response to indicate the version-id-marker value of the next ListObjectVersions (GetBucketVersions) request. Parent nodes: ListVersionsResult
MaxKeys	String	1000	The maximum number of objects that can be returned in the response. Parent nodes: ListVersionsResult
Name	String	examplebucket-1250000000	The name of the bucket. Parent nodes: ListVersionsResult
Owner	Container	N/A	The container that stores the information about the bucket owner. 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	The container that stores the versions of objects, excluding delete markers. Parent nodes: ListVersionsResult
DeleteMarker	Container	N/A	The container that stores delete markers. Parent nodes: ListVersionsResult
ETag	String	250F8A0AE989679A22926A875F0A2****	The ETag that is generated when an object is created. ETags are used to identify the content of objects. If an object is created by calling the PutObject operation, the ETag of the object is the MD5 hash of the object content. If an object is created by using another method, the ETag is not the MD5 hash of the object content but a unique value that is calculated based on a specific rule. Note The ETag of an object can be used only to check whether the object content was modified. We recommend that you use the MD5 hash of an object instead of the ETag of the object 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 returned objects were last modified. Note The minimum storage duration (30 days) of IA objects is calculated based on the last modified time of the objects. If the value of the Last-Modified header is 30 days earlier than the current time, you are not charged for the storage usage of the IA object that is stored for less than the minimum storage duration. The minimum storage duration (60 days) of Archive objects is calculated based on the last modified time of the objects. If the value of the Last-Modified header is 60 days earlier than the current time, you are not charged for the storage usage of the Archive object that is stored for less than the minimum storage duration. Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker
TransitionTime	Time	2024-04-23T07:21:42.000Z	The time when the storage class of the returned objects is changed to Cold Archive or Deep Cold Archive based on lifecycle rules. Note If the object is stored for more than 180 days after the storage class of the object is converted, you are not charged for the storage usage of the Cold Archive or Deep Cold Archive object that is stored for less than the minimum storage duration. If the object is stored for less than 180 days after the storage class of the object is converted, you are charged for the storage usage of the Cold Archive or Deep Cold Archive object that is stored for less than the minimum storage duration. You cannot use this header to query the time when the storage class of the object is converted to Infrequent Access (IA) or Archive based on lifecycle rules. You can determine whether the object is stored for more than the minimum storage duration based on the value of the `Last-Modified` header. 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	Indicates whether the version is the current version. Valid values: true false Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker
Size	String	93731	The size of the object. Unit: bytes. Parent nodes: ListVersionsResult.Version and ListVersionsResult.DeleteMarker
StorageClass	String	Standard	The storage class of the object. 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 restoration status of the object. If no RestoreObject requests are sent or the requests expire, this field is not included in the response. If a RestoreObject request is sent but the restoration is not complete, the value of this response parameter is `ongoing-request="true"`. If a RestoreObject request is sent and the restoration is complete, the value of this response parameter is in the `ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"` format, in which the `expiry-date` field 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

In this example, two objects named example and pic.jpg are stored in a bucket named oss-example. The object named example has the following three versions that are displayed by creation time in descending order: 111222, 000123 (delete marker), and 222333. The object named pic.jpg has only one version whose ID is 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

In this example, the examplebucket bucket contains the following Cold Archive objects: exampleobject1.txt, exampleobject2.txt, and exampleobject3.txt. The three objects are in the following states:

No RestoreObject requests are sent to restore exampleobject1.txt or the RestoreObject requests sent to restore the object have expired.
A RestoreObject request is sent to restore exampleobject2.txt and the object is being restored.
A RestoreObject request is sent to restore exampleobject3.txt and the object is restored.

Sample requests

GET / HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 08:43:27 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>
    <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>

SDK

You can use OSS SDKs for the following programming languages to call the ListObjectVersions (GetBucketVersions) operation:

Error codes

Error code	HTTP status code	Description
NoSuchBucket	404	The requested bucket does not exist. Check whether the name of the requested bucket complies with the naming rules.
AccessDenied	403	You do not have the permissions to access the bucket. Only the bucket owner and RAM users who are granted the `oss:ListObjectVersions` permission can access the bucket.
InvalidArgument	400	The value of max-keys is less than 0 or greater than 1,000. The length of the value of prefix, marker, or delimiter is invalid.