Docs

Torch Object Storage

Basic Object Operations

GetObject

Function Description

This interface is used to download a specified object from a bucket. Only the bucket owner or authorized users have permission to call this interface to download objects. In a multi-version scenario, if no version number is specified, the current version of the object will be downloaded; if versionId is specified, the designated version of the object will be returned.

Server-Side Encryption

If the object to be downloaded uses server-side encryption with TOS-managed encryption keys (SSE-TOS) or KMS-managed encryption keys (SSE-KMS), you should not include encryption request header fields in the GET request, such as x-tos-server-side-encryption. If you include such an encryption header field, you will receive 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.

Precautions

Before downloading objects from Archive Storage, Cold Archive Storage, or Deep Cold Archive Storage using the GetObject API, you must first restore the objects.

Anonymous Request Explanation

TOS does not allow custom response headers in GET requests made via anonymous access. For details, please refer to the Object Storage Anonymous Request Restriction Explanation.

Request syntax

Request parameters and headers

For the public request header of this request, see Common parameters.

Name	Location	Type	Required	Sample Value	Description
Range	Header	String	No	bytes=0-4	Scope of acquisition for specified objects. If not specified, the entire object is retrieved. A Range represents a sequence whose starting value can be as low as 0 and as high as the object's length minus 1. The starting value of the Range parameter is required. If Range contains only the starting value, it indicates retrieval of the object content from the starting value to object length minus one, inclusive. The format is: bytes=start-end. tip After including the Range header, the ETag in the response message remains the object's ETag, rather than the ETag of the object within the specified Range.
If-Match	Header	String	No	8a36be0d764367db4eea2deb16b71543	The object is returned only if the provided 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 is returned only if it has been modified since the specified time; otherwise, a 304 Not Modified status is returned. The time format is RFC1123 GMT.
If-None-Match	Header	String	No	8a36be0d764367db4eea2deb16b71543	The object is returned only if the provided 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 is returned only if it has not been modified since the specified 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, mandatory when using SSE-C encryption.	AES256	This header field is used when the object is encrypted with SSE-C. It specifies the algorithm used to decrypt the object. The possible values are explained 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.	YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWE=	Used in conjunction with x-tos-server-side-encryption-customer-algorithm, specifies the key for SSE-C encryption of the target object, which is a base64-encoded 256-bit encryption key.
x-tos-server-side-encryption-customer-key-md5	Header	String	No. Required when using SSE-C encryption.	0gYVWExOAz67jX5A6qY4+A==	This header field is used when encrypting objects with SSE-C and works in conjunction with x-tos-server-side-encryption-customer-key. It indicates 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.
x-tos-traffic-limit	Header	String	No	819200	TOS provides single-link rate limiting functionality, enabling flow control during operations such as file upload and download to ensure network bandwidth for other applications. The values are described as follows: Value range: 245760–838860800, unit: bit/s This parameter cannot exist simultaneously in Header and Query.
x-tos-traffic-limit	Query	String	No	819200	TOS provides single-link rate limiting, implementing flow control during operations such as file upload and download to ensure network bandwidth for other applications. The values are explained as follows: Value range: 245760–838860800, unit: bit/s This parameter cannot be present in both Header and Query at the same time.
response-content-disposition	Query	String	No	attachment; filename=123.txt	Specify the Content-Disposition response header returned by the server.
response-content-encoding	Query	String	No	gzip	Specify the Content-Encoding response header returned by the server.
response-content-language	Query	String	No	en-US	Specify the Content-Language response header returned by the server.
response-content-type	Query	String	No	text/plain	Specify the Content-Type response header returned by the server.
response-expires	Query	String	No	Mon, 04 Jul 2022 02:57:31 GMT	Specify the Expires response header returned by the server.
versionId	Query	String	No	123	Retrieve the object with the specified version number.

Request body elements

There is no request element in this request message.

Response headers

This request returns public response message headers. Please refer to Common parameters.

tip

When downloading an object using the GetObject API, if the object type is a soft link object, the content returned in different response headers will vary. The details are as follows:

Content-Length, ETag, x-tos-storage-class, and x-tos-hash-crc64ecma: Return information about the target object referenced by the symbolic link object.

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

Other response headers: Returns information about symbolic link objects.

Name	Type	Sample Value	Description
Content-Range	String	bytes 0-4/300	Scope of returned object data.
Last-Modified	String	Mon, 02 Jul 2021 10:29:28 GMT	Object Last Update Date.
x-tos-delete-marker	Bool	true	Whether the object is marked for deletion. If not, this message header will not be returned.
x-tos-server-side-encryption	String	kms	This header field is returned when the object is encrypted using SSE-TOS or SSE-KMS, indicating the server-side encryption method applied to the object. Possible values are as follows: AES256: Uses the SSE-TOS encryption method and the AES256 encryption algorithm. SM4: Uses SSE-TOS encryption mode and adopts the SM4 encryption algorithm. kms: Use the 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:20000111:keyrings/ring-test/keys/key-test	This header field is returned when an object uses SSE-KMS encryption and indicates the KMS master key ID used for SSE-KMS encryption.
x-tos-server-side-encryption-customer-algorithm	String	AES256	This header is returned when the object is encrypted with 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 settings, 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 meaning of its values is as follows: Appendable: This object is uploaded via the append-write interface. Symlink: This object is a symbolic link object.
x-tos-storage-class	String	STANDARD	The possible values for the object's storage type are as follows: STANDARD: Standard storage. IA: Infrequent access storage. INTELLIGENT_TIERING: intelligent tiered storage. ARCHIVE_FR: Flashback Archive storage. ARCHIVE: Archive storage. COLD_ARCHIVE: Cold archive storage. DEEP_COLD_ARCHIVE: Deep cold archive storage.
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 Tiered Storage INFREQUENT: Infrequent Access tier of Intelligent Tiered Storage ARCHIVEFR: Flashback Archive tier of Intelligent Tiered Storage 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 of 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 rule, 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 states for the replication status of an object, whether it is replicated across regions or within the same region: If the object is from the source bucket, the parameter takes the following values: COMPLETE: The object has been successfully copied to the target bucket. PENDING: This object is being replicated. FAILED: Failed to copy the object. If the object is in the target storage bucket, this parameter has only one possible value, which is 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 by cross-region or same-region replication rules. Querying the replication status of objects is only supported for source storage buckets configured with a single cross-region or same-region replication rule. For example, if multiple replication rules are set in the source bucket to replicate 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, the storage type is ARCHIVE, COLD_ARCHIVE, or DEEP_COLD_ARCHIVE), the copy deletion time will be returned, for example, ongoing-request="false", expiry-date="Sat, 1 Jan 2022 00:00:00 GMT".
x-tos-qos-delay-time	Integer	10	This header field indicates the duration for which the request is subject to flow control, measured in ms. Upload requests return the precise duration affected by rate limiting; copy requests or download requests return an estimated duration affected by rate limiting, based on the degree of rate limiting and the file size.
x-tos-directory	Bool	true	This header field will be returned if 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 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 specifies the period 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 body elements

There is no message element in this request response.

Sample request

Sample response

Last updated: 2025.11.24 14:47:11