Get the metadata of an object - Object Storage Service - Alibaba Cloud Documentation Center

The HeadObject operation retrieves the metadata of an object. This operation does not return the object content.

Versioning

If you call the HeadObject operation without specifying `versionId` in the request, the metadata of the current version of the object is returned. If the current version is a delete marker, OSS returns 404 NoSuchKey.
If you call the HeadObject operation and specify a `versionId` in the request, the metadata of the specified version is returned. You cannot specify the `versionId` of a delete marker. If you do, OSS returns 405 MethodNotAllowed.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM Policy or Bucket Policy.

API	Action	Definition
HeadObject	`oss:GetObject`	Queries the metadata of an object.

Request syntax

HEAD /ObjectName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue

Request headers

Name	Type	Required	Description
If-Modified-Since	String	No	If the time specified in this header is earlier than the actual modification time of the object, OSS returns 200 OK and the object metadata. Otherwise, OSS returns 304 Not Modified. Default: none
If-Unmodified-Since	String	No	If the time specified in this header is the same as or later than the actual modification time of the object, OSS returns 200 OK and the object metadata. Otherwise, OSS returns 412 Precondition Failed. Default: none
If-Match	String	No	If the ETag specified in this header matches the ETag of the object, OSS returns 200 OK and the object metadata. Otherwise, OSS returns 412 Precondition Failed. Default: none
If-None-Match	String	No	If the ETag specified in this header does not match the ETag of the object, OSS returns 200 OK and the object metadata. Otherwise, OSS returns 304 Not Modified. Default: none

This operation also uses common request headers, such as Host and Date. For more information, see Common request headers.

Response headers

If the requested object is a symbolic link, the response headers are as follows:

Content-Length, ETag, x-oss-storage-class, and Content-Md5 are the metadata of the target object.
Last-Modified is the more recent of the last modification time of the symbolic link and the last modification time of the target object.
Other response headers indicate the metadata of the symbolic link.

Name	Type	Description
x-oss-meta-*	String	A parameter prefixed with x-oss-meta- is a user-defined metadata header. If you set custom metadata prefixed with x-oss-meta- when you call the PutObject operation, the response includes these custom metadata headers.
Custom headers that do not start with x-oss-meta-	String	If you specify custom headers that do not start with the `x-oss-meta-` prefix during a PutObject operation, such as `x-oss-persistent-headers`:`key1:base64_encode(value1),key2:base64_encode(value2)...`, the response will include these headers.
x-oss-server-side-encryption	String	If the object is stored with server-side encryption, this header is returned in the response. The value of this header indicates the server-side encryption algorithm used for the object.
x-oss-server-side-encryption-key-id	String	If you use server-side encryption with KMS when you create an object, the response includes this header. It indicates the ID of the KMS key used for encryption.
x-oss-storage-class	String	The storage class of the object. Valid values: Standard, Infrequent Access (IA), Archive Storage, Cold Archive, and Deep Cold Archive. For more information, see Storage classes.
x-oss-object-type	String	The type of the object. Objects uploaded by calling PutObject or created by calling CreateDirectory are of the Normal type. Objects uploaded by calling AppendObject are of the Appendable type. Objects uploaded by calling MultipartUpload are of the Multipart type.
x-oss-next-append-position	String	This header is returned for Appendable objects. It specifies the position from which the next append operation must start.
x-oss-hash-crc64ecma	String	The 64-bit CRC value of the object. The value is calculated based on the CRC-64/XZ algorithm. For objects created before OSS supported CRC-64 checks, this response header may not be returned when you call the HeadObject operation.
x-oss-sealed-time	String	This header is returned for Appendable objects that are in the Sealed state. It indicates the time when the object was sealed. The time is in GMT format as specified in HTTP 1.1, such as Sat, 11 Oct 2025 06:41:42 GMT.
x-oss-transition-time	String	The time when the object was transitioned to the Cold Archive or Deep Cold Archive storage class by a lifecycle rule. 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.
x-oss-expiration	String	The expiration time of an object in a bucket for which a lifecycle rule is configured. Bucket with versioning enabled Request without a versionId If the requested object matches a deletion rule in the lifecycle configuration, the x-oss-expiration header is returned in the response. This header indicates the expiration time of the current version of the object. Request with a versionId The x-oss-expiration header is not returned in the response, regardless of whether the requested object matches a deletion rule in the lifecycle configuration. Bucket with versioning disabled If the requested object matches a deletion rule in the lifecycle configuration, the x-oss-expiration header is returned in the response. If the requested object does not match a deletion rule in the lifecycle configuration, the x-oss-expiration header is not returned in the response.
x-oss-restore	String	If the storage class of the object is Archive Storage, Cold Archive, or Deep Cold Archive, and you have submitted a RestoreObject request, the x-oss-restore header is returned in the response to indicate the restoration status of the object. The status can be one of the following: If no RestoreObject request is submitted or the restored object has expired, this header is not returned. If a RestoreObject request is submitted but the restoration is not complete, the value of x-oss-restore is ongoing-request="true". If a RestoreObject request is submitted and the restoration is complete, the value of x-oss-restore is ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT". The expiry-date indicates when the restored object is no longer readable.
x-oss-process-status	String	After you create an OSS event notification using Simple Message Queue (SMQ), if an OSS operation matches an event notification rule, the response includes this header. The value is the Base64-encoded result of the event notification in JSON format.
x-oss-request-charged	String	If the bucket to which the object belongs is set to the pay-by-requester mode and the requester is not the bucket owner, the response includes this header with the value requester.
Content-Md5	String	For Normal objects, this is the Base64-encoded 128-bit MD5 hash of the message content (excluding headers), calculated according to RFC 1864. This header is not returned for Multipart or Appendable objects.
Last-Modified	String	The date and time when the object was last modified. The format is GMT as specified in HTTP 1.1. 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.
Access-Control-Allow-Origin	String	If the bucket that contains the object has a CORS rule configured and the request origin matches the specified CORS rule, this origin is included in the response.
Access-Control-Allow-Methods	String	If the bucket that contains the object has a CORS rule configured and the Access-Control-Request-Method of the request matches the specified CORS rule, the allowed methods are included in the response.
Access-Control-Max-Age	String	If the bucket that contains the object has a CORS rule configured and the request matches the CORS rule, MaxAgeSeconds is included in the response.
Access-Control-Allow-Headers	String	If the bucket that contains the object has a CORS rule configured and the request matches the specified CORS rule, these headers are included in the response.
Access-Control-Expose-Headers	String	A list of headers that client-side JavaScript programs are allowed to access. If the bucket that contains the object has a CORS rule configured and the request matches the specified CORS rule, ExposeHeader is included in the response.
x-oss-tagging-count	String	The number of tags associated with the object. This header is returned only if you have the permission to read tags.

This operation also uses common response headers, such as ETag and x-oss-request-id. For more information, see Common response headers.

Examples

Versioning disabled

Request sample

HEAD /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 07:32:52 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Response sample (for an object that is a file)

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Normal
x-oss-storage-class: Archive
Date: Fri, 7 Aug 2020 07:32:52 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

Response sample (for an object that is a folder)

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Normal
x-oss-storage-class: Standard
Date: Wed, 31 Mar 2021 07:32:52 GMT
Last-Modified: Tue, 30 Mar 2021 06:07:48 GMT
ETag: "null"
Content-Length: 0
Content-Type: application/x-directory
Connection: keep-alive
Server: AliyunOSS

Response sample (for a sealed Appendable object)

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Appendable
x-oss-storage-class: Standard
x-oss-sealed-time: Sat, 11 Oct 2025 06:41:42 GMT
Date: Wed, 31 Mar 2021 07:32:52 GMT
Last-Modified: Tue, 30 Mar 2021 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 100
Content-Type: text/plain
Connection: keep-alive
Server: AliyunOSS

Requesting a specific version of an object (versioning enabled)

Request sample

HEAD /example?versionId=CAEQNRiBgICb8o6D0BYiIDNlNzk5NGE2M2Y3ZjRhZTViYTAxZGE0ZTEyMWYy****
Host: versioning-test.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 06:27:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Response sample

HTTP/1.1 200 OK
x-oss-versionId: CAEQNRiBgICb8o6D0BYiIDNlNzk5NGE2M2Y3ZjRhZTViYTAxZGE0ZTEyMWYy****
x-oss-request-id: 5CAC3B40B7AEADE01700****
x-oss-object-type: Normal
x-oss-storage-class: Archive
Date: Fri, 7 Aug 2020 06:27:12 GMT
Last-Modified: Fri, 7 Aug 2020 06:27:12 GMT
ETag: "A082B659EF78733A5A042FA253B1****"
Content-Length: 481827
Content-Type: text/html
Connection: keep-alive
Server: AliyunOSS

Requesting the latest version of an object (versioning enabled)

Request sample

HEAD /example HTTP/1.1    
Host: versioning-test.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 06:27:12 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Response sample

HTTP/1.1 200 OK
x-oss-versionId: CAEQMxiBgMCZov2D0BYiIDY4MDllOTc2YmY5MjQxMzdiOGI3OTlhNTU0ODIx****
x-oss-request-id: 5CAC3B40B7AEADE01700****
x-oss-object-type: Normal
x-oss-storage-class: Archive
Date: Fri, 7 Aug 2020 06:27:12 GMT
Last-Modified: Fri, 7 Aug 2020 06:27:12 GMT
ETag: "3663F7B0B9D3153F884C821E7CF4****"
Content-Length: 485859
Content-Type: text/html
Connection: keep-alive
Server: AliyunOSS

A RestoreObject request was submitted, but the restoration is not complete.

Request sample

HEAD /oss.jpg HTTP/1.1
Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 07:32:52 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Response sample

HTTP/1.1 200 OK
x-oss-request-id: 58F71A164529F18D7F00****
x-oss-object-type: Normal
x-oss-storage-class: Archive
x-oss-restore: ongoing-request="true"
Date: Fri, 7 Aug 2020 07:32:52 GMT
Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

A RestoreObject request was submitted, and the restoration is complete.

Request sample

HEAD /oss.jpg HTTP/1.1
Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 09:35:51 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Response sample

HTTP/1.1 200 OK
x-oss-request-id: 58F725344529F18D7F00****
x-oss-object-type: Normal
x-oss-storage-class: Archive
x-oss-restore: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT"
Date: Fri, 7 Aug 2020 09:35:51 GMT
Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606

Using server-side encryption with SSE-OSS

Request sample

HEAD /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 07:32:52 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Response sample

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A6448****
x-oss-object-type: Normal
x-oss-storage-class: Archive
x-oss-server-side-encryption: AES256
Date: Fri, 7 Aug 2020 07:32:52 GMT
Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

Using server-side encryption with SSE-KMS

Request sample

HEAD /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 7 Aug 2020 07:32:52 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Response sample

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC755F95A64485981
x-oss-object-type: Normal
x-oss-storage-class: Archive
x-oss-server-side-encryption: KMS
x-oss-server-side-encryption-key-id: 9468da86-3509-4f8d-a61e-6eab1eac****
Date: Fri, 7 Aug 2020 07:32:52 GMT
Last-Modified: Fri, 7 Aug 2020 06:07:48 GMT
ETag: "fba9dede5f27731c9771645a3986****"
Content-Length: 344606
Content-Type: image/jpg
Connection: keep-alive
Server: AliyunOSS

SDK

This operation is available in the following SDKs:

ossutil command-line interface

For the ossutil command that corresponds to the HeadObject operation, see head-object.

Error codes

Error code	HTTP status code	Description
NoSuchKey	404	The requested object does not exist.
SymlinkTargetNotExist	404	The requested file is a symbolic link.
InvalidTargetType	400	The requested object is a symbolic link, and its target object is also a symbolic link.
NotModified	304	This error is returned for one of the following reasons: The If-Modified-Since request header is specified, but the source object has not been modified since the specified time. The If-None-Match request header is specified, and the ETag of the source object is the same as the ETag you provided.
PreconditionFailed	412	This error is returned for one of the following reasons: The If-Unmodified-Since header is specified, but the specified time is earlier than the actual modification time of the object. The If-Match header is specified, but the ETag of the source object is not the same as the ETag you provided.