Docs

Torch Object Storage

Basic Object Operations

HeadObject

Description

This interface is used to obtain the metadata of an object without returning the object itself. This operation is particularly useful if you are only interested in the metadata of the object. To use HEAD, you must have READ access to the object.

HEAD requests have the same options as GET operations on objects. The response is identical to a GET response, except that it does not include a response body. Therefore, if a HEAD request results in an error, it will return a generic 404 Not Found or 403 Forbidden code.

Server-side encryption

If an object uses server-side encryption with TOS-managed keys (SSE-TOS) or server-side encryption with KMS-managed keys (SSE-KMS), encryption request headers such as x-tos-server-side-encryption should not be included in HEAD requests. Including such encryption headers will result in an HTTP 400 BadRequest error.

If the client uses a customer-provided encryption key (SSE-C) for server-side encryption when uploading an object, you must include the following headers when downloading the object:

x-tos-server-side-encryption-customer-algorithm

x-tos-server-side-encryption-customer-key

x-tos-server-side-encryption-customer-key-MD5

For more detailed information about server-side encryption, please refer to Server-side encryption overview.

Request syntax

Request parameters and headers

Please refer to Common Parameters for the common request headers used by this request.

Name	Location	Type	Required	Example value	Description
If-Match	Header	String	No	8a36be0d764367db4eea2deb16b71543	The object metadata is returned only if the provided expected ETag matches the object's ETag; otherwise, a 412 Precondition Failed response is returned.
If-Modified-Since	Header	String	No	Mon, 04 Jul 2022 02:57:31 GMT	The object's metadata is returned only if the time specified in the input parameter is earlier than the object's actual modification time; otherwise, a 304 Not Modified response is returned. The time format is RFC1123 GMT.
If-None-Match	Header	String	No	8a36be0d764367db4eea2deb16b71543	The object metadata is returned only if the provided expected ETag does not match the object's ETag; otherwise, a 304 Not Modified response is returned.
If-Unmodified-Since	Header	String	No	Mon, 04 Jul 2022 02:57:31 GMT	The object's metadata is returned only if the time specified in the input parameter is equal to or later than the object's actual modification time; otherwise, a 412 Precondition Failed response is returned. The time format is RFC1123 GMT.
x-tos-server-side-encryption-customer-algorithm	Header	String	No	AES256	This header field is used when accessing an object that has been encrypted with SSE-C. It specifies the algorithm to be used for decrypting the object. The possible values are described as follows: AES256: Encrypts objects using the AES256 algorithm.
x-tos-server-side-encryption-customer-key	Header	String	No. Required when using SSE-C encryption.	YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFh****	When used in conjunction with x-tos-server-side-encryption-customer-algorithm, this parameter specifies the encryption key for the SSE-C encrypted target object. The key must be a base64-encoded 256-bit encryption key.
x-tos-server-side-encryption-customer-key-MD5	Header	String	No	0gYVWExOAz67jX5A6qY****	This header field is used when encrypting objects with SSE-C and is used in conjunction with x-tos-server-side-encryption-customer-key. This header field represents the MD5 value of the key used to decrypt the object. This header field is generated by base64 encoding the 128-bit MD5 value of the key. This value is used for message integrity verification to ensure that the encryption key has not been corrupted during transmission.
versionId	Query	String	No	57AF1A32CECB56721267	The version number of the object. Identifies the retrieval of object metadata for a specified version.

Request elements

There is no request element in this request message.

Response headers

Please refer to Public parameters for the public response headers returned by this request.

tip

When using HeadObject to retrieve object metadata, if the object type is a symbolic link object, the content returned by different response headers will vary. The details are as follows:

ETag, x-tos-storage-class, x-tos-hash-crc64ecma, and x-tos-symlink-target-size: Returns information about the target object referenced by the symbolic link object.

Last-Modified: Returns the later modification date between the soft link object and the target object.

Other response headers: Provide information about soft link objects.

Name	Type	Example value	Description
Last-Modified	String	Mon, 02 Jul 2021 10:29:28 GMT	The object's last update time.
x-tos-delete-marker	Bool	true	Indicates whether the object is marked as deleted. If not, the message header will not appear in the response.
x-tos-server-side-encryption	String	kms	This header field is returned when the object is encrypted using SSE-TOS or SSE-KMS. It indicates the server-side encryption method for the object, with possible values as follows: AES256: Uses the SSE-TOS encryption method and applies the AES256 encryption algorithm. SM4: Uses the SSE-TOS encryption mode and employs the SM4 encryption algorithm. kms: Use SSE-KMS encryption method. For detailed information on SSE-TOS and SSE-KMS encryption methods, please refer to the Server-side encryption overview.
x-tos-server-side-encryption-kms-key-id	String	trn:kms:cn-beijing:****:keyrings/ring-test/keys/key-test	This header field is returned when an object uses SSE-KMS encryption. It indicates the KMS master key ID used for SSE-KMS encryption.
x-tos-server-side-encryption-customer-algorithm	String	AES256	This header field is returned when the object is encrypted using SSE-C and indicates the algorithm used for decryption.
x-tos-server-side-encryption-customer-key-MD5	String	0gYVWExOAz67jX5A6qY4+A==	This header field is returned when an object is encrypted using SSE-C and indicates the MD5 value of the key used for decryption.
x-tos-version-id	String	57AF1A32CECB56721267	The version number of the object. If the version number does not exist, this message header will not appear in the response message.
x-tos-website-redirect-location	String	/abc	When a bucket is configured with Website configuration, requests to retrieve this object can be redirected to another object within the bucket or to an external URL. TOS extracts this value from the header and stores it in the object's metadata.
x-tos-object-type	String	Symlink	When the object is not a Normal object, this response header will be returned. The description of its values is as follows: Appendable: This object is uploaded via the append-write interface. Symlink: This object is a symbolic link.
x-tos-symlink-target-size	Integer	10000	When the object is a soft link object, this header field is returned to indicate the size of the target object pointed to by the soft link object.
x-tos-storage-class	String	STANDARD	Storage type of the object. The possible values are explained as follows: STANDARD: Standard Storage. IA: Infrequent Access Storage. INTELLIGENT_TIERING: Intelligent Tiering. ARCHIVE_FR: Flashback Archive. ARCHIVE: Archive. COLD_ARCHIVE: Cold Archive. DEEP_COLD_ARCHIVE: Deep Cold Archive.
x-tos-storage-tier	String	INFREQUENT	The access level of the intelligent tiered object, with values described as follows: FREQUENT: Frequent Access tier of Intelligent Tiering. INFREQUENT: Infrequent Access tier of Intelligent Tiering. ARCHIVEFR: Flashback Archive tier of Intelligent Tiering. tip The x-tos-storage-tier parameter is returned only for intelligent tiered objects.
x-tos-hash-crc64ecma	Integer	6186290338114851376	Represents the 64-bit CRC value of this object. The 64-bit CRC is calculated in accordance with the ECMA-182 standard. tip For objects created before the TOS server supported 64-bit CRC validation, this message header will not appear in the response message.
x-tos-tagging-count	String	3	Number of labels for the object. Returned only if object tag read permission is granted.
X-Tos-Expiration	String	expiry-date="Sun, 25 Dec 2022 00:00:00 GMT"	There are two possible scenarios regarding the expiration date of the object: If the object matches the lifecycle deletion rules, the following parameters are returned: expiry-date: The expiration date of the object. rule-id: Lifecycle rule ID. If the object has an expiration time set, the expiry-date parameter will be returned to indicate the object's expiration date, while the rule-id parameter will be empty.
x-tos-replication-status	String	COMPLETE	There are two possible scenarios regarding the status of object cross-region replication or intra-region replication: If the object is from the source bucket, this parameter takes the following value: COMPLETE: The object has been successfully copied to the destination bucket. PENDING: This object is being copied. FAILED: Failed to copy the object. If the object is in the target storage bucket, this parameter has only one value, REPLICA, indicating that the object was synchronized through cross-region or same-region replication. warning The object cross-region or same-region replication status query feature (i.e., the x-tos-replication-status parameter) is currently in invitation-only testing. If you require access to this feature, please contact your account manager. This parameter is returned only when the object is in the source bucket or destination bucket specified in cross-region or same-region replication rules. Only querying the object replication status is supported for source storage buckets configured with a single cross-region or same-region replication rule. For example, if multiple cross-region replication rules are set in the source storage bucket to copy object A to buckets B, C, and D, querying the replication status of object A is not supported. Objects in the target bucket are not subject to this restriction.
x-tos-restore	String	ARCHIVE	If the object is an archive, cold archive, or deep cold archive object (that is, its storage class is ARCHIVE, COLD_ARCHIVE, or DEEP_COLD_ARCHIVE), this header field will be returned after the Restore Object operation is performed. The details are as follows: If a copy is being generated, the return value is ongoing-request="true". If a copy has been generated, the expiration time of the copy will be returned, for example, ongoing-request="false", expiry-date="Sat, 1 Jan 2022 00:00:00 GMT".
x-tos-restore-request-date	String	Sat, 1 Jan 2022 00:00:00 GMT	If the object is an archive, cold archive, or deep cold archive object (that is, the storage type is ARCHIVE, COLD_ARCHIVE, or DEEP_COLD_ARCHIVE), and the Restore Object operation has been performed, this header field will be returned during replica generation to indicate the time the Restore Object operation was executed. For example, Sat, 1 Jan 2022 00:00:00 GMT.
x-tos-restore-expiry-days	Integer	7	If the object is an archive, cold archive, or deep cold archive object (that is, the storage type is ARCHIVE, COLD_ARCHIVE, or DEEP_COLD_ARCHIVE), and the Restore Object operation has been performed, this header field will be returned during replica generation to indicate the number of valid days for the replica.
x-tos-restore-tier	String	Standard	The recovery priority of archive-type files: During replica generation, this header field will be returned. The explanation is as follows: The recovery priority for archived storage objects can only be Standard, which means that restoration of archived storage objects will be completed within 1 minute. The recovery priority values for cold archive objects are as follows: Expedited: Rapid retrieval, recovery completed within 1 to 5 minutes. Standard: Standard retrieval, recovery is completed within 2 to 5 hours. Bulk: Batch retrieval; recovery completed within 5–12 hours. The restoration priority values for deep cold archive objects are as follows: Standard: Standard retrieval, recovery completed within 12 hours. Bulk: Bulk retrieval, recovery completed within 48 hours.
x-tos-directory	Bool	true	This header field is returned when the bucket type is hierarchical bucket and the file type is directory.
x-tos-create-time	String	Mon, 02 Jul 2021 10:29:28 GMT	Creation date of the object.
x-tos-object-lock-mode	String	COMPLIANCE	The mode of the object retention policy can only be set to COMPLIANCE, which indicates compliance mode. tip Your account must have the GetObjectRetention permission for the x-tos-object-lock-mode parameter to be returned.
x-tos-object-lock-retain-until-date	String	2025-01-01T00:00:00Z	The lock expiration date of the object is the date during which the object cannot be deleted or overwritten. tip Your account must have the GetObjectRetention permission for the x-tos-object-lock-retain-until-date parameter to be returned.

Response elements

There are no message elements in the response to this request.

Request example

Response example

Last updated: 2026.08.03 10:32:55