All Products
Search

This Product

    Object Storage Service:HeadObject

    Document Center

    Object Storage Service:HeadObject

    Last Updated:Jun 08, 2026

    The HeadObject operation retrieves the metadata of an object without returning the object content.

    Versioning

    • If you call HeadObject without specifying a versionId, the metadata of the current version is returned. If the current version is a delete marker, OSS returns 404 NoSuchKey.

    • If you call HeadObject with a specific versionId, the metadata of that version is returned. Do not specify the versionId of a delete marker; otherwise, 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 policies 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 specified time is earlier than the object's actual modification time, OSS returns 200 OK with the object metadata. Otherwise, OSS returns 304 Not Modified.

    Default value: None

    If-Unmodified-Since

    String

    No

    If the specified time is the same as or later than the object's actual modification time, OSS returns 200 OK with the object metadata. Otherwise, OSS returns 412 Precondition Failed.

    Default value: None

    If-Match

    String

    No

    If the specified ETag matches the ETag of the object, OSS returns 200 OK with the object metadata. Otherwise, OSS returns 412 Precondition Failed.

    Default value: None

    If-None-Match

    String

    No

    If the specified ETag does not match the ETag of the object, OSS returns 200 OK with the object metadata. Otherwise, OSS returns 304 Not Modified.

    Default value: None

    This operation also supports Common request headers such as Host and Date.

    Response headers

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

    • Content-Length, ETag, x-oss-storage-class, and Content-Md5 are the metadata of the object file.

    • Last-Modified is the last modification time of the symbolic link or the object file, whichever is later.

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

    Name

    Type

    Description

    x-oss-meta-*

    String

    User-defined metadata headers set via PutObject with the x-oss-meta- prefix are returned in the response.

    Custom headers that do not start with x-oss-meta-

    String

    Custom headers that do not start with x-oss-meta- (for example, x-oss-persistent-headers:key1:base64_encode(value1),key2:base64_encode(value2)...) set via PutObject are returned in the response.

    x-oss-server-side-encryption

    String

    Returned if the object uses server-side encryption. The value indicates the encryption algorithm.

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

    String

    Returned if the object uses KMS-based server-side encryption. The value is the KMS key ID.

    x-oss-storage-class

    String

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

    Storage classes.

    x-oss-object-type

    String

    The type of the object.

    • Objects that are uploaded by calling PutObject or created by calling CreateDirectory are of the Normal type.

    • Objects that are uploaded by calling AppendObject are of the Appendable type.

    • Objects that are uploaded by calling MultipartUpload are of the Multipart type.

    x-oss-next-append-position

    String

    Returned for Appendable objects. Indicates the position from which the next append operation starts.

    x-oss-hash-crc64ecma

    String

    The CRC-64 value of the object, calculated using the CRC-64/XZ algorithm.

    This header may not be returned for objects created before OSS supported CRC-64.

    x-oss-sealed-time

    String

    Returned for sealed Appendable objects. Indicates when the object was sealed, in HTTP 1.1 GMT format (for example, Sat, 11 Oct 2025 06:41:42 GMT).

    x-oss-transition-time

    String

    The time when the object was converted to Cold Archive or Deep Cold Archive by a lifecycle rule.

    Note

    • If you delete a Cold Archive or Deep Cold Archive object more than 180 days after it is converted, no early deletion fee is charged. If you delete the object within 180 days after it is converted, an early deletion fee is charged.

    • This field cannot be used to determine the time when an object is converted to the IA or Archive storage class by a lifecycle rule. Whether an IA or Archive object meets the minimum storage duration requirement depends on the Last-Modified time.

    x-oss-expiration

    String

    The expiration time of an object in a bucket with lifecycle rules configured.

    • Versioning is enabled for the bucket

      • A request is sent without a versionId.

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

      • A request is sent with a versionId.

        The x-oss-expiration header is not returned in the response, regardless of whether the requested object matches a delete rule in the lifecycle configuration.

    • Versioning is disabled for the bucket

      • If the requested object matches a delete rule in the lifecycle configuration, the x-oss-expiration header is returned in the response.

      • If the requested object does not match a delete rule in the lifecycle configuration, the x-oss-expiration header is not returned in the response.

    x-oss-restore

    String

    If the object's storage class is Archive, ColdArchive, or DeepColdArchive and a Restore request has been submitted, the restore status is returned in this header:

    • If no Restore request has been submitted or the restored object has expired, this header is not returned.

    • If the restore is in progress, the value is ongoing-request="true".

    • If the restore is complete, the value is ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT", where expiry-date indicates when the restored copy expires.

    x-oss-process-status

    String

    If an OSS event notification is created using Simple Message Queue (SMQ) and a matching rule exists, this header is returned. The value is the Base64-encoded event notification result in JSON format.

    x-oss-request-charged

    String

    Returned if the bucket uses pay-by-requester mode and the requester is not the bucket owner. The value is requester.

    Content-Md5

    String

    • For Normal objects, this is the Base64-encoded 128-bit MD5 hash of the message content (excluding headers), calculated per RFC 1864.

    • This header is not returned for Multipart or Appendable objects.

    Last-Modified

    String

    The last modification time of the object, in HTTP 1.1 GMT format.

    Note

    • The minimum storage duration for objects in the Infrequent Access storage class is 30 days. The duration is calculated from the Last-Modified time of the object. If you delete an object more than 30 days after its Last-Modified time, no early deletion fee is charged.

    • The minimum storage duration for objects in the Archive Storage class is 60 days. The duration is calculated from the Last-Modified time of the object. If you delete an object more than 60 days after its Last-Modified time, no early deletion fee is charged.

    Access-Control-Allow-Origin

    String

    Returned if the bucket has a CORS rule configured and the request origin matches the rule.

    Access-Control-Allow-Methods

    String

    Returned if the bucket has a CORS rule configured and the Access-Control-Request-Method matches the rule.

    Access-Control-Max-Age

    String

    Returned if the bucket has a CORS rule configured and the request matches the rule. Indicates the preflight cache duration.

    Access-Control-Allow-Headers

    String

    Returned if the bucket has a CORS rule configured and the request matches the rule.

    Access-Control-Expose-Headers

    String

    The headers that client-side JavaScript is allowed to access. Returned if the bucket has a CORS rule configured and the request matches the rule.

    x-oss-tagging-count

    String

    The number of tags associated with the object. Returned only if you have permission to read tags.

    This operation also supports Common response headers such as ETag and x-oss-request-id.

    Examples

    • Versioning is disabled

      Request example

      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 example (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

      Response example (The object 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 example (The object is 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 is enabled)

      Request example

      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 example

      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 is enabled)

      Request example

      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 example

      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

    • Restore task in progress

      Request example

      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 example

      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

    • Restore task complete

      Request example

      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 example

      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 example

      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 example

      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 example

      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 example

      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

    SDKs

    Supported SDKs:

    ossutil

    The corresponding ossutil command is 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 that you provided.

    PreconditionFailed

    412

    This error is returned for one of the following reasons:

    • The If-Unmodified-Since request header is specified, but the specified time is earlier than the actual modification time of the object.

    • The If-Match request header is specified, but the ETag of the source object is not the same as the ETag that you provided.