Skip to main content

HeadObject

The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you're interested only in an object's metadata.

note

A HEAD request has the same options as a GET operation on an object. The response is identical to the GET response except that there is no response body. Because of this, if the HEAD request generates an error, it returns a generic code, such as 400 Bad Request, 403 Forbidden, 404 Not Found, 405 Method Not Allowed, 412 Precondition Failed, or 304 Not Modified. It's not possible to retrieve the exact exception of these error codes.

Permissions​

ActionDescriptionResource
GetObjectGrants permission to retrieve an object from a bucketobject
GetObjectVersionGrants permission to retrieve a specific version of an object from a bucketobject

Versioning

  • If the current version of the object is a delete marker, Astran S3 behaves as if the object was deleted and includes x-amz-delete-marker: true in the response.
  • If the specified version is a delete marker, the response returns a 405 Method Not Allowed error and the Last-Modified: timestamp response header.

The following actions are related to HeadObject:

Request Syntax​

HEAD /Bucket/Key+?response-cache-control=ResponseCacheControl&versionId=VersionId HTTP/1.1
Host: <partition>.s3.astran.io
Range: Range
x-amz-checksum-mode: ChecksumMode

URI Request Parameters​

The request uses the following URI parameters.

Bucket

The name of the bucket that contains the object.

Required: Yes

Key

The object key.

Length Constraints: Minimum length of 1.

Required: Yes

Range

HeadObject returns only the metadata for an object. If the Range is satisfiable, only the ContentLength is affected in the response. If the Range is not satisfiable, S3 returns a 416 - Requested Range Not Satisfiable error.

response-cache-control

Sets the Cache-Control header of the response.

versionId

Version ID used to reference a specific version of the object.

x-amz-checksum-mode

To retrieve the checksum, this parameter must be enabled.

Valid Values: ENABLED

Request Body​

The request does not have a request body.

Response Syntax​

HTTP/1.1 200
x-amz-delete-marker: DeleteMarker
accept-ranges: AcceptRanges
Last-Modified: LastModified
Content-Length: ContentLength
x-amz-checksum-crc32: ChecksumCRC32
x-amz-checksum-type: ChecksumType
ETag: ETag
x-amz-version-id: VersionId
Cache-Control: CacheControl
Content-Range: ContentRange

Response Elements​

If the action is successful, the service sends back an HTTP 200 response.

The response returns the following HTTP headers.

accept-ranges

Indicates that a range of bytes was specified.

Cache-Control

Specifies caching behavior along the request/reply chain.

Content-Length

Size of the body in bytes.

Content-Range

The portion of the object returned in the response for a GET request.

ETag

An entity tag (ETag) is an opaque identifier assigned by a web server to a specific version of a resource found at a URL.

Last-Modified

Date and time when the object was last modified.

x-amz-checksum-crc32

The Base64 encoded, 32-bit CRC32 checksum of the object. This checksum is only be present if the checksum was uploaded with the object. When you use an API operation on an object that was uploaded using multipart uploads, this value may not be a direct checksum value of the full object. Instead, it's a calculation based on the checksum values of each individual part. For more information about how checksums are calculated with multipart uploads, see Checking object integrity in the _Astran S3 User Guide.

x-amz-checksum-type

The checksum type, which determines how part-level checksums are combined to create an object-level checksum for multipart objects. You can use this header response to verify that the checksum type that is received is the same checksum type that was specified in CreateMultipartUpload request. For more information, see Checking object integrity in the Astran S3 User Guide.

Valid Values: COMPOSITE | FULL_OBJECT

x-amz-delete-marker

Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.

x-amz-version-id

Version ID of the object.

Errors​

NoSuchKey

The specified key does not exist.

HTTP Status Code: 404

Examples​

Sample Request for general purpose buckets​

The following request returns the metadata of an object.


            HEAD /bucket/my-image.jpg HTTP/1.1
            Host: <partition>.s3.astran.io
            Date: Wed, 28 Oct 2009 22:32:00 GMT
            Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0RonhpaBX5sCYVf1bNRuU=

Sample Response for general purpose buckets​

This example illustrates one usage of HeadObject.


            HTTP/1.1 200 OK
            x-request-id: 318BC8BC143432E5
            x-amz-version-id: 3HL4kqtJlcpXroDTDmjVBH40Nrjfkd
            Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
            ETag: "fba9dede5f27731c9771645a39863328"
            Content-Length: 434234

Sample Request for general purpose buckets: Getting metadata from a specified version of an object​

The following request returns the metadata of the specified version of an object.


            HEAD /bucket/my-image.jpg?versionId=3HL4kqCxf3vjVBH40Nrjfkd HTTP/1.1
            Host: <partition>.s3.astran.io
            Date: Wed, 28 Oct 2009 22:32:00 GMT
            Authorization: AWS AKIAIOSFODNN7EXAMPLE:02236Q3V0WpaBX5sCYVf1bNRuU=

Sample Response for general purpose buckets: To a versioned HEAD request​

This example illustrates one usage of HeadObject.


            HTTP/1.1 200 OK
            x-request-id: 318BC8BC143432E5
            x-amz-version-id: 3HL4kqtJlcpXrof3vjVBH40Nrjfkd
            Last-Modified: Sun, 1 Jan 2006 12:00:00 GMT
            ETag: "fba9dede5f27731c9771645a39863328"
            Content-Length: 434234

See Also​

For more information about using this API in one of the language-specific AWS SDKs, see the following: