Get object retention

To get an object's retention configuration you make a GET request that is scoped to the object, and you use the retention query string parameter. If the object has a retention configuration, the configuration is returned in an XML document in the response body. Otherwise, the request fails with a 404 Not Found response.

You must have READ permission to get an object's retention configuration.

Query string parameters

Parameter Description Required
retention Return the object's retention configuration. No
generation Specifies the generation on which to set the retention configuration. No

See signed URL query string parameters for information on the parameters you include when creating and using signed URLs.

Request headers

See common request headers.

Request body elements

This request does not include an XML document in the request body.

Request syntax

The following syntax applies to GET Object requests that use the retention query string parameter.

GET /OBJECT_NAME?retention&generation=GENERATION HTTP/1.1
Content-Length: 0
Content-Type: TYPE

Response headers

The request can return a variety of response headers depending on the request headers you use.

Response body elements

The following response body elements are applicable only if you use the retention query string parameter.

Element Description
Retention Container for an object's retention configuration.
Mode Mode of the object retention configuration. GOVERNANCE corresponds to unlocked mode, and COMPLIANCE corresponds to locked mode.
RetainUntilDate A date and time represented in RFC 3339 UTC format that indicates the time until which the object is retained as immutable.


The following example retrieves the retention configuration for an object named tokyo.jpg.


GET /tokyo.jpg?retention HTTP/1.1
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg


HTTP/1.1 200 OK
Content-Length: 138
Content-Type: application/xml; charset=UTF-8
Date: Tue, 01 Nov 2016 17:12:32 GMT

<?xml version="1.0" encoding="UTF-8"?>