Call GetObjectRetention to retrieve the object retention policy for a specific object version, including its retention mode and retain until date.
Usage notes
Before calling this operation, you must enable the object-level retention policy (ObjectWorm) for the bucket by calling PutBucketObjectWormConfiguration.
To call this operation, you must have the
oss:GetObjectRetentionpermission.If no object retention policy is configured for the object and no default object-level retention policy is configured for the bucket, the Mode and RetainUntilDate in the returned Retention element are empty.
Request syntax
GET /ObjectName?retention HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValueRequest parameters
Parameter | Type | Required | Example | Description |
retention | N/A | Yes | N/A | Specifies the operation to retrieve the object retention policy. |
versionId | string | No | CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** | The version ID of the object. If omitted, the operation retrieves the retention policy for the latest version of the object. |
Response elements
Parameter | Type | Example | Description |
Retention | container | N/A | A container for the object retention policy information. Child nodes: Mode and RetainUntilDate |
Mode | string | COMPLIANCE | The object's retention mode. COMPLIANCE indicates compliance mode. This node is empty if no retention policy is configured. Parent node: Retention |
RetainUntilDate | string | 2026-10-11T00:00:00.000Z | The retain until date for the object version. The date is in ISO 8601 format. The object version cannot be deleted or overwritten before this date. This node is empty if no retention policy is configured. Parent node: Retention |
Examples
Request example
GET /exampleobject?retention&versionId=CAEQNhiBgMDJgZCA0BYiIDc4MGZj**** HTTP/1.1 Date: Thu, 17 Mar 2026 11:18:32 GMT Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260317/cn-hangzhou/oss/aliyun_v4_request,Signature=****Response example
HTTP/1.1 200 OK x-oss-request-id: 5374A2880232A65C2300**** Date: Thu, 17 Mar 2026 11:18:32 GMT Content-Type: application/xml Transfer-Encoding: chunked Server: AliyunOSS <?xml version="1.0" encoding="UTF-8"?> <Retention> <Mode>COMPLIANCE</Mode> <RetainUntilDate>2026-10-11T00:00:00.000Z</RetainUntilDate> </Retention>