All Products
Search

This Product

    Object Storage Service:HeadObject

    Document Center

    Object Storage Service:HeadObject

    Last Updated:Apr 26, 2025

    HeadObject is used to query the metadata of an object. When you call this operation, the object content is not returned in the results.

    Versioning

    • If you do not specify the versionId parameter in a HeadObject request, the metadata of the current version of the object is returned. If the current version of the object is a delete marker, Object Storage Service (OSS) returns the HTTP status code 404 and the NoSuchKey error code.

    • If you specify the versionId parameter in a HeadObject request, the metadata of the specified version of the object is returned. If you specify the version ID of a delete marker in a HeadObject request, OSS returns the HTTP status code 405 and the MethodNotAllowed error code.

    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

    Description

    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 input time is earlier than the actual modification time, the object metadata and 200 OK are returned. Otherwise, 304 Not Modified is returned.

    Default value: null

    If-Unmodified-Since

    string

    No

    If the specified time is equal to or later than the last modified time of the object, the object metadata and 200 OK are returned. Otherwise, 412 Precondition Failed is returned.

    Default value: null

    If-Match

    string

    No

    If the ETag value that is specified in the request matches the ETag value of the object, OSS returns the metadata of the object and 200 OK. Otherwise, OSS returns 412 precondition failed.

    Default value: null

    If-None-Match

    string

    No

    If the ETag value that is specified in the request does not match the ETag value of the object, OSS returns the metadata of the object and 200 OK. Otherwise, OSS returns 304 Not Modified.

    Default value: null

    For more information about the common request headers such as Host and Date contained in HeadObject requests, see Common Request Headers.

    Response headers

    If the requested object is a symbolic link, note the following headers in the response:

    • Content-Length, ETag, x-oss-storage-class, and Content-Md5 are the metadata of the object to which the symbolic link points.

    • The returned value of Last-Modified uses the last modified time of the symbolic link or the last modified time of the object to which the symbolic link points, whichever is later.

    • Other response headers are the metadata of the symbolic link.

    Name

    Type

    Description

    x-oss-meta-*

    string

    The user metadata that is prefixed with x-oss-meta-. If you specify headers prefixed with x-oss-meta- in a PutObject request, the user metadata of the object is included in the response.

    Custom headers that are not prefixed with x-oss-meta-

    string

    If you specify custom headers that are not prefixed with x-oss-meta- in a PutObject request, such as x-oss-persistent-headers:key1:base64_encode(value1)，key2:base64_encode(value2)...., these custom headers are included in the response.

    x-oss-server-side-encryption

    string

    If the object is encrypted by using server-side entropy encoding, this header is included in the response to indicate the server-side encryption algorithm that is used to encrypt the object.

    x-oss-server-side-encryption-key-id

    string

    This header is included in the response if the object is encrypted by using Key Management Service (KMS) on the server side. The value of this header is the customer master key (CMK) ID that is used to encrypt the object.

    x-oss-storage-class

    string

    The storage class of the object. Valid values: Standard, IA, Archive, ColdArchive, and DeepColdArchive.

    For more information, see Storage classes.

    x-oss-object-type

    string

    The type of the object. Valid values:

    • Normal: The object is uploaded by using PutObject or created by using CreateDirectory.

    • Appendable: The object is uploaded by using AppendObject.

    • Multipart: The object is uploaded by using MultipartUpload.

    x-oss-next-append-position

    string

    The position for the next append operation. If the type of the object is Appendable, this header is included in the response.

    x-oss-hash-crc64ecma

    string

    The 64-bit CRC value of the object. This value is calculated based on the ECMA-182 standard.

    If an object is created before OSS supports CRC-64, this header may not be included in the response when you call HeadObject to query the metadata of the object.

    x-oss-transition-time

    string

    The time when the storage class of the object is converted to Cold Archive or Deep Cold Archive based on lifecycle rules.

    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 the object in the bucket for which lifecycle rules are configured.

    • Versioning enabled for the bucket

      • Version ID not included in the request

        If the object requested matches the delete conditions specified in the lifecycle rule, the x-oss-expiration header is included in the response to indicate the expiration time of the current version of the object.

      • Version ID included in the request

        The x-oss-expiration header is not included in the response regardless of whether the object requested matches the delete conditions specified in the lifecycle rule.

    • If versioning is disabled for the bucket

      • If the object requested matches the delete conditions specified in the lifecycle rule, the x-oss-expiration header is included in the response.

      • If the object requested does not match the delete conditions specified in the lifecycle rule, the x-oss-expiration header is not included in the response.

    x-oss-restore

    string

    The status of the object when you restore an object. If a RestoreObject request is submitted for an Archive, Cold Archive, or Deep Cold Archive object, this header is included in the response.

    • If the RestoreObject request is not submitted or expires, this header is not included in the response.

    • If the RestoreObject request is submitted and the restoration is incomplete, the returned value of this header is ongoing-request="true".

    • If the RestoreObject request is submitted and the restoration is complete, the return value of this header is in the following format: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT". The value of the expiry-date parameter indicates the time before which the restored object can be read.

    x-oss-process-status

    string

    When a user creates an OSS event notification by using Simple Message Queue (SMQ) and performs an operation on OSS that matches an event notification rule, this header is included in the response. The value of this header is the event notification result in the JSON format that is encoded in Base64.

    x-oss-request-charged

    string

    The requester. This header is included in the response if the pay-by-requester mode is enabled for the bucket and the requester is not the bucket owner. The value of this header is requester.

    Content-Md5

    string

    • This header is included in the response if the object type is Normal. The value of this header is calculated based on the following process: 1. Calculate the MD5 hash of the message content based on RFC 1864 to obtain a 128-bit digit. Do not include headers to calculate the MD5 hash. 2. Encode the digit by using Base64.

    • If the object type is Multipart or Appendable, this header is not included in the response.

    Last-Modified

    string

    The time when the object was last modified. The time is in GMT 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

    The origins allowed for cross-origin resource sharing (CORS). If a CORS rule is configured for the bucket that stores the object and the Origin header in the request meets the CORS rule, this header is included in the response.

    Access-Control-Allow-Methods

    string

    The methods allowed for CORS. If a CORS rule is configured for the bucket that stores the object and the Access-Control-Request-Method header in the request meets the CORS rule, this header is included in the response.

    Access-Control-Max-Age

    string

    The maximum caching period for CORS. If a CORS rule is configured for the bucket that stores the object and the request meets the CORS rule, this header is included in the response.

    Access-Control-Allow-Headers

    string

    The headers allowed for CORS. If a CORS rule is configured for the bucket that stores the object and the request meets the CORS rule, this header is included in the response.

    Access-Control-Expose-Headers

    string

    The list of header fields that can be accessed by JavaScript applications on the client. If a CORS rule is configured for the bucket that stores the object and the request meets the CORS rule, this header is included in the response.

    x-oss-tagging-count

    string

    The number of tags added to the object. This header is included in the response only when you have read permissions on tags.

    For more information about the common response headers such as ETag and x-oss-request-id contained in the responses to HeadObject requests, see Common Response Headers.

    Examples

    • Query the metadata of an object in an unversioned bucket

      Command

      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

      Sample success responses (when the object 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

      Sample success responses for a directory 

      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

    • Query the metadata of an object of the specified version in a versioned bucket

      Command

      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

      Sample output 

      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

    • Query the metadata of an object of the current version in a versioned bucket

      Command

      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

      Sample output 

      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

    • Query the metadata of an object for which the RestoreObject request is submitted and restoration is in progress

      Command

      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

      Sample output 

      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

    • Query the metadata of an object for which the RestoreObject request is submitted and restoration is complete

      Command

      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

      Sample output 

      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

    • Query the metadata of an object that is encrypted by using the server-side encryption method SSE-OSS

      Command

      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

      Sample output

      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

    • Query the metadata of an object that is encrypted by using the server-side encryption method SSE-KMS

      Command

      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

      Sample output

      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

    You can use OSS SDKs for the following programming languages to call HeadObject:

    Command-line tool ossutil

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

    Error codes

    Error code

    HTTP status code

    Description

    NoSuchKey

    404

    The error message returned because the requested object does not exist.

    SymlinkTargetNotExist

    404

    The error message returned because the requested object is a symbolic link.

    InvalidTargetType

    400

    The error message returned because the requested object is a symbolic link that points to another symbolic link.

    NotModified

    304

    The error message returned because of the following possible causes:

    • The If-Modified-Since request header is specified, but the source object has not been modified after the specified time.

    • The If-None-Match request header is specified, and the ETag value of the source object is the same as the ETag value that you provide.

    PreconditionFailed

    412

    The error message returned because of the following possible causes:

    • 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 value of the source object is different from the ETag value that you provide.