listObjectVersions method
Written by
Updated at September 30, 2024
Returns metadata for all versions of objects in the bucket.
You can also use request parameters as a selection criterion to return metadata about a subset of object versions.
For more information on getting started with the API and the general request format, see How to use the S3 API.
Request
GET /{bucket}?versions&delimiter=Delimiter&encoding-type=EncodingType&key-marker=KeyMarker&max-keys=MaxKeys&prefix=Prefix&version-id-marker=VersionIdMarker HTTP/2
Path parameters
Parameter | Description |
---|---|
bucket |
Bucket name. |
Query parameters
All parameters listed in the table are optional.
Parameter | Description |
---|---|
delimiter |
Delimiter character. If this parameter is specified, Object Storage interprets the key as the path to the file with folders separated by the delimiter character. In the response to the request, the user will get a list of files and folders in the bucket. Files will be output in the Contents elements, and folders in the CommonPrefixes elements.If the request also specifies the prefix parameter, Object Storage will return the list of files and folders in the folder named prefix . |
encoding-type |
Encoding of server response. Object Storage can encode responses in the format requested by the client. Possible values: url . |
key-marker |
Key to start the output from. In the resulting output, Object Storage will leave the keys starting from the one following key-marker . |
max-keys |
Maximum number of elements in a response. By default, Object Storage outputs no more than 1,000 Contents and CommonPrefixes elements. Use this parameter if you need less than 1,000 elements in a single response.If the selection criteria are met by more keys than can fit into the output, the response contains <IsTruncated>true</IsTruncated> .To get all output elements if their number exceeds max-keys , run multiple requests to Object Storage with the key-marker parameter, where key-marker and version-id-marker of each request is equal to the value of the NextKeyMarker and NextVersionIdMarker elements in the previous response. |
prefix |
String to start the key from. Object Storage selects only those keys which start with prefix .You can use this parameter along with delimiter . In this case, the output logic is the same as that specified in the delimiter parameter description. |
version-id-marker |
Object version to start the output from. In the resulting output, Object Storage will leave the versions starting from the one following version-id-marker . |
Headers
Use only common request headers in your requests.
Response
Headers
Responses can only contain common response headers.
Response codes
For a list of possible responses, see Responses.
A successful response contains additional data in XML format with the schema described below.
Data schema
<?xml version="1.0" encoding="UTF-8"?>
<ListVersionsResult>
<IsTruncated>boolean</IsTruncated>
<KeyMarker>string</KeyMarker>
<VersionIdMarker>string</VersionIdMarker>
<NextKeyMarker>string</NextKeyMarker>
<NextVersionIdMarker>string</NextVersionIdMarker>
<Version>
<ETag>string</ETag>
<IsLatest>boolean</IsLatest>
<Key>string</Key>
<LastModified>timestamp</LastModified>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
<Size>integer</Size>
<StorageClass>string</StorageClass>
<VersionId>string</VersionId>
</Version>
...
<DeleteMarker>
<IsLatest>boolean</IsLatest>
<Key>string</Key>
<LastModified>timestamp</LastModified>
<Owner>
<DisplayName>string</DisplayName>
<ID>string</ID>
</Owner>
<VersionId>string</VersionId>
</DeleteMarker>
...
<Name>string</Name>
<Prefix>string</Prefix>
<Delimiter>string</Delimiter>
<MaxKeys>integer</MaxKeys>
<CommonPrefixes>
<Prefix>string</Prefix>
</CommonPrefixes>
...
<EncodingType>string</EncodingType>
</ListVersionsResult>
Element | Description |
---|---|
ListVersionsResult |
Root element |
CommonPrefixes |
Key name part identified when processing the delimiter and prefix query parameters.Path: /ListVersionsResult/CommonPrefixes . |
DeleteMarker |
Container for an object that is a delete marker. Path: /ListVersionsResult/DeleteMarker . |
Delimiter |
Value of the delimiter query parameter.Path: /ListVersionsResult/Delimiter . |
EncodingType |
Encoding used by Object Storage to provide a key in an XML response. Appears if the client provided the encoding-type parameter in the request.Path: /ListVersionsResult/EncodingType . |
IsTruncated |
Marker indicating that a list is incomplete. If IsTruncated is true , this means Object Storage returned an incomplete list of parts.Path: /ListVersionsResult/IsTruncated . |
KeyMarker |
The last key returned in the incomplete response. Path: /ListVersionsResult/KeyMarker . |
MaxKeys |
Value of the max-keys query parameter.Path: /ListBucketResult/MaxKeys . |
Name |
Bucket name. Path: /ListBucketResult/Name . |
NextKeyMarker |
Value to insert in the key-marker query parameter to get the next part of the list if the entire list does not fit in the current response.Path: /ListBucketResult/NextMarker . |
NextVersionIdMarker |
Value to insert in the version-id-marker query parameter to get the next part of the list if the entire list does not fit in the current response.Path: /ListBucketResult/NextVersionIdMarker . |
Prefix |
Value of the prefix query parameter.Path: /ListBucketResult/Prefix . |
Version |
Object version. Path: /ListBucketResult/Version . |
VersionIdMarker |
Marks the latest version of the key returned in the truncated response. Path: /ListBucketResult/VersionIdMarker . |