Get an Object

Updated at：2025-11-03

API description

This command retrieves an object from BOS. The requester must have read permission for the object. You can specify the range of the object's data to retrieve by setting the range in the header.

Note:

GetObject supports resumable uploads based on the range parameter. This feature is recommended for larger objects.

If the Range parameter is included in the request header, the response will contain the total file length and the returned range. For example, Content-Range: bytes 0-9/44 indicates the file's total length is 44 and the returned range is 0-9.

Attempting to read a 0-byte object with the Range parameter will result in a 400 error. The Range is a closed interval at both ends.

Objects stored in the archive class must be restored before invoking the GetObject API.

If you want to obtain specific header information in the response request, the following two methods are available:

Add header information during the PutObject operation to enable direct return of this information in the response during the GetObject operation. Refer to the PutObject API for details.
Add "responseXXX=YYY" directly in the queryString during GetObject operation to include "XXX: YYY" in the response header. For example: GET /testBucket/testObject?responseContentType= image/jpg. In the response requested by HTTP, there is "Content-Type: image/jpg". The specific format is response$header=urlencode(value). It should be noted that the current $header only supports "ContentDisposition, ContentType, ContentLanguage, Expires, CacheControl and ContentEncoding".

Note: responseContentDisposition setting has domain name in BOS ($region.bcebos.com and *.$region.bcebos.com are invalid).

Request URI

GET /v1/{bucketName}/{objectKey}

Parameter name	Parameter type	Required or not	Description	Example value	Parameter location
bucketName	String	Yes	Bucket name	"bucketName_example"	Path
objectKey	String	Yes	Object name	"objectKey_example"	Path

Request header parameters

Parameter name	Parameter type	Required or not	Description	Example value
range	String	No	Specify the range of the file to be returned. For example, set bytes=0-9 to transmit 10 characters from the 0th to the 9th. By default, all data is returned.	"range_example"

Parameters of request body

Description of the data structure of request body fields

Response header parameters

Parameter name	Parameter type	Description
Cache-Control	String	Cache settings for downloading the object. Common values include private, no-cache, max-age, must-revalidate
Content-Disposition	String	Set whether the browser downloads the file; available values are inline, attachment; filename="download.txt"
Content-Length	String	Size of data returned to the object
Content-Range	String	Range of data returned to the object when the range is set up
Content-Type	String	Object type and encoding method
Expires	String	Cache expiration time when the object is downloaded
ETag	String	The HTTP protocol entity tag of object
x-bce-meta-*	String	This item is returned only if custom meta exists
x-bce-storage-class	String	STANDARD is returned for standard storage, STANDARD_IA for infrequent access storage, COLD for cold storage, and ARCHIVE for archive storage. For multi-AZ class buckets, MAZ_STANDARD_IA is returned for multi-AZ infrequent access storage and MAZ_STANDARD for multi-AZ standard storage.
x-bce-server-side-encryption	String	Currently, the only supported server-side encryption type for objects is AES256.

Response body parameters

Description of the data structure of response body fields

Request example

                JSON
                
                GET /v1/bucketName_example/objectKey_example
 <Common request headers>
Range: range_example
{ }

Response example

                JSON
                
                HTTP/1.1 200 OK
 <Common response headers>
{ }

Error code

Please refer to the general error codes

Restore Archived Files

Fetch an Object and Store It in a Bucket