tencent cloud

APIs

DocumentationAPIsCloud Object StorageObject APIsBasic OperationsGET Object

GET Object

Download
Focus Mode
Font Size
Last updated: 2026-06-22 16:42:29

Feature Description

This API is used to download an object in a COS bucket to a local file system. To call this API, you need to have permission to read the object, or the object is set to
Note:
If the response-* parameter is used in a request, anonymous access will not be supported and the request must carry a signature.
When origin-pull is configured through the COS console Set Origin and Sync Origin is not enabled, note that when COS pulls data from the configured origin server, a GET Object request will return a 302 redirect to the origin-pull address. If the origin-pull address is untrusted, it is strongly recommended not to follow the -302 redirect directly when using the SDK or calling the API. Instead, have your backend service verify the legitimacy of the origin-pull address before requesting it to avoid security risks such as SSRF (for example, origin-pulling to an internal network address).


Authorization Description

Set the action in the authorization policy to cos:GetObject. For all available actions, see the list.

Versioning

When versioning is enabled, the versionId request parameter can be used in the GET operation to specify the version ID to return. In this case, the specified version of the object will be returned. If the specified version is a delete marker, HTTP status code 404 (Not Found) is returned. Otherwise, the latest version of the specified object is returned.

Archive storage classes

If the object targeted by the GET request is of Archive or Deep Archive storage classes and has not been restored using POST Object restore (or the restored copy has expired and been deleted), the request will return HTTP status code 403 (Forbidden) with an error message in the response body. The error code (Code) will be InvalidObjectState, indicating that the current state of the object cannot be accessed by the GET request and needs to be restored first.

Request

Request Example

GET /<ObjectKey> HTTP/1.1
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com
Date: GMT Date
Authorization: Auth String
Note:
Host: <BucketName-APPID>.cos.<Region>.myqcloud.com, where <BucketName-APPID> is the bucket name with the APPID suffix, such as examplebucket-1250000000. You can refer to the Bucket Overview > Basic Information and Bucket Overview > Bucket Naming Convention documentation. <Region> represents the available regions for COS, which can be found in the Regions and Access Domain Names documentation.
Authorization: Auth String (For details, see Request Signature).

Request Parameter

Term
Description
Type
Required
response-cache-control
Sets the value of the Cache-Control header in the response
string
No
response-content-disposition
Sets the value of the Content-Disposition header in the response
string
No
response-content-encoding
Sets the value of the Content-Encoding header in the response
string
No
response-content-language
Sets the value of the Content-Language header in the response
string
No
response-content-type
Sets the value of the Content-Type header in the response
string
No
response-expires
Sets the value of the Expires header in the response
string
No
versionId
Version ID to download when versioning is enabled. If it is not specified, the latest version of the object is downloaded.
string
No

Request Header

In addition to using common request headers, this API also supports the following request headers. For details about common request headers, see Common Request Headers.
Term
Description
Type
Required
Range
Byte range defined in RFC 2616, the range value must be in the format of bytes=first-last and only supports a single range, not multiple ranges. Both first and last are offsets starting from 0.
Range: bytes=0-0 specifies the first byte of the object to be downloaded.
Range: bytes=0-9 specifies the first 10 bytes of the object to be downloaded.
Range: bytes=5-9 specifies bytes 6 through 10 of the object to be downloaded. In this case, HTTP status code 206 (Partial Content) and the Content-Range response header are returned.
Range: bytes=-10 specifies the last 10 bytes of the object to be downloaded.
Range: bytes=10- specifies bytes 10 through the end of the object to be downloaded.
Range: bytes=0- specifies bytes from the first to the last byte of the object to be downloaded, which is the complete file content.
When only part of the byte data is downloaded, HTTP status code 206 (Partial Content) and the Content-Range response header are returned.
If the values of both first and last exceed the size of the object, HTTP status code 416 (Requested Range Not Satisfiable) error is returned.
If it is not specified, the entire object is downloaded.
string
No
If-Modified-Since
If the object is modified after the specified time, the object is returned; otherwise, HTTP status code 304 (Not Modified) is returned.
string
No
If-Unmodified-Since
If the object is not modified after the specified time, the object is returned; otherwise, HTTP status code 412 (Precondition Failed) is returned.
string
No
If-Match
If the ETag of the object matches the specified value, the object is returned; otherwise, HTTP status code 412 (Precondition Failed) is returned.
string
No
If-None-Match
If the ETag of the object does not match the specified value, the object is returned; otherwise, HTTP status code 304 (Not Modified) is returned.
string
No
x-cos-traffic-limit
The speed limit for traffic control in this download must be a numeric value, with the default unit being bit/s. The speed limit range is set between 819,200 and 838,860,800, that is, 800 Kb/s to 800 Mb/s. If it exceeds this range, a 400 error will be returned.
integer
No
Server-side Encryption-related Headers
If server-side encryption is used for the specified object and the encryption method is SSE-C, you will need to specify the headers related to server-side encryption to decrypt the object. For more information, see Server-side Encryption Headers.

Request Body

This API has no request body.

Response

Response Headers

In addition to common response headers, this API returns the following response headers. For details about common response headers, see Common Response Headers.
Term
Description
Type
Cache-Control
Cache instruction defined in RFC 2616, which is returned only if it is contained in the object metadata or specified in the request parameters.
string
Content-Disposition
File name defined in RFC 2616, which is returned only if it is contained in the object metadata or specified in the request parameters.
string
Content-Encoding
Encoding format defined in RFC 2616, which is returned only if it is contained in the object metadata or specified in the request parameters.
string
Content-Range
Byte range of the content to be returned defined in RFC 2616, which is returned only when a Range request header is specified in the request.
string
Expires
Cache expiration time defined in RFC 2616, which is returned only if it is contained in the object metadata or specified in the request parameters.
string
x-cos-meta-*
Includes the user-defined metadata header suffix and user-defined metadata information.
string
x-cos-storage-class
Storage class of the object. For the enumeration values, see the Storage Class document, for example, MAZ_STANDARD, MAZ_STANDARD_IA, INTELLIGENT_TIERING, MAZ_INTELLIGENT_TIERING, STANDARD_IA, ARCHIVE, DEEP_ARCHIVE. This header is returned only when the object is not stored as STANDARD.
enum
x-cos-storage-tier
When the storage class of the object is INTELLIGENT_TIERING, this header indicates the storage tier where the object resides. Valid values: FREQUENT, INFREQUENT.
enum
Versioning-related headers
The following table describes the response headers returned for objects in a versioning-enabled bucket.
Term
Description
Type
x-cos-version-id
Version ID of an object.
string
Server-side Encryption-related Headers
If server-side encryption is used for the specified object, this API will return the server-side encryption headers. For more information, see Server-side Encryption Headers.

Response Body

The response body of this API request is the object (file) content.

Error Codes

This API follows unified error responses and error codes. For details, see Error Codes.

Practical Case

Example III: simple use case (with versioning disabled)

Request

GET /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 10 Apr 2020 09:35:16 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1586511316;1586518516&q-key-time=1586511316;1586518516&q-header-list=date;host&q-url-param-list=&q-signature=****************************************

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 16
Connection: close
Accept-Ranges: bytes
Date: Fri, 10 Apr 2020 09:35:16 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Last-Modified: Fri, 10 Apr 2020 09:35:05 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 16749565679157681890
x-cos-request-id: NWU5MDNkZDRfZDgyNzVkNjRfN2Q5M18xOWVi****



[Object Content]

Sample 2: specifying response headers through request parameters

Request

GET /exampleobject?response-content-type=application%2Foctet-stream&response-cache-control=max-age%3D86400&response-content-disposition=attachment%3B%20filename%3Dexample.jpg HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 10 Apr 2020 09:35:17 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1586511317;1586518517&q-key-time=1586511317;1586518517&q-header-list=date;host&q-url-param-list=response-cache-control;response-content-disposition;response-content-type&q-signature=****************************************
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 16
Connection: close
Accept-Ranges: bytes
Cache-Control: max-age=86400
Content-Disposition: attachment; filename=example.jpg
Date: Fri, 10 Apr 2020 09:35:17 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Last-Modified: Fri, 10 Apr 2020 09:35:05 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 16749565679157681890
x-cos-request-id: NWU5MDNkZDVfNjZjODJhMDlfMTY2MDdfMThm****



[Object Content]

Sample 3: specifying search criteria through the request headers with HTTP status code 304 (Not Modified) returned

Request

GET /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Wed, 29 Jul 2020 06:51:49 GMT
If-None-Match: "ee8de918d05640145b18f70f4c3aa602"
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1596005509;1596012709&q-key-time=1596005509;1596012709&q-header-list=date;host;if-none-match&q-url-param-list=&q-signature=****************************************
Connection: close

Response

HTTP/1.1 304 Not Modified
Content-Type: image/jpeg
Content-Length: 0
Connection: close
Date: Wed, 29 Jul 2020 06:51:49 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Server: tencent-cos
x-cos-hash-crc64ecma: 16749565679157681890
x-cos-request-id: NWYyMTFjODVfOGZiNzJhMDlfNDcxZjZfZDY2****

Sample 4: specifying search criteria through the request header with HTTP status code 412 (Precondition Failed) returned

Request

GET /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Wed, 29 Jul 2020 06:51:50 GMT
If-Match: "aa488bb80185a6be87f4a7b936a80752"
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1596005510;1596012710&q-key-time=1596005510;1596012710&q-header-list=date;host;if-match&q-url-param-list=&q-signature=****************************************
Connection: close

Response

HTTP/1.1 412 Precondition Failed
Content-Type: application/xml
Content-Length: 480
Connection: close
Date: Wed, 29 Jul 2020 06:51:50 GMT
Server: tencent-cos
x-cos-request-id: NWYyMTFjODZfOGRjOTJhMDlfMmIyMWVfOTJl****



<?xml version='1.0' encoding='utf-8' ?>
<Error>
            <Code>PreconditionFailed</Code>
            <Message>Precondition not match.</Message>
            <Resource>examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Resource>
            <RequestId>NWYyMTFjODZfOGRjOTJhMDlfMmIyMWVfOTJl****</RequestId>
            <TraceId>OGVmYzZiMmQzYjA2OWNhODk0NTRkMTBiOWVmMDAxODc0OWRkZjk0ZDM1NmI1M2E2MTRlY2MzZDhmNmI5MWI1OTdjMDczODYwZjM5YTU3ZmZmOWI5MmY4NjkxY2I3MGNiNjkyOWZiNzUxZjg5MGY2OWU4NmI0YWMwNTlhNTExYWU=</TraceId>
</Error>

Sample 5: using server-side encryption SSE-COS

Request

GET /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 10 Apr 2020 09:36:00 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1586511360;1586518560&q-key-time=1586511360;1586518560&q-header-list=date;host&q-url-param-list=&q-signature=****************************************
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 16
Connection: close
Accept-Ranges: bytes
Date: Fri, 10 Apr 2020 09:36:00 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Last-Modified: Fri, 10 Apr 2020 09:35:49 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 16749565679157681890
x-cos-request-id: NWU5MDNlMDBfMzdiMDJhMDlfYTgyNl8xNjA2****
x-cos-server-side-encryption: AES256



[Object Content]

Sample 6: using server-side encryption SSE-KMS

Request

GET /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 10 Apr 2020 09:36:11 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1586511371;1586518571&q-key-time=1586511371;1586518571&q-header-list=date;host&q-url-param-list=&q-signature=****************************************
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 16
Connection: close
Accept-Ranges: bytes
Date: Fri, 10 Apr 2020 09:36:11 GMT
ETag: "840af7c921f4b3230049af8663145bd0"
Last-Modified: Fri, 10 Apr 2020 09:36:01 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 16749565679157681890
x-cos-request-id: NWU5MDNlMGJfZGEyNzVkNjRfZDgxY18xYTBj****
x-cos-server-side-encryption: cos/kms
x-cos-server-side-encryption-cos-kms-key-id: 48ba38aa-26c5-11ea-855c-52540085****



[Object Content]

Sample 7: using server-side encryption SSE-C

Request

GET /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 10 Apr 2020 09:36:23 GMT
x-cos-server-side-encryption-customer-algorithm: AES256
x-cos-server-side-encryption-customer-key: MDEyMzQ1Njc4OUFCQ0RFRjAxMjM0NTY3ODlBQkNERUY=
x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1586511383;1586518583&q-key-time=1586511383;1586518583&q-header-list=date;host;x-cos-server-side-encryption-customer-algorithm;x-cos-server-side-encryption-customer-key;x-cos-server-side-encryption-customer-key-md5&q-url-param-list=&q-signature=************************************
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 16
Connection: close
Accept-Ranges: bytes
Date: Fri, 10 Apr 2020 09:36:23 GMT
ETag: "582d9105f71525f3c161984bc005efb5"
Last-Modified: Fri, 10 Apr 2020 09:36:12 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 16749565679157681890
x-cos-request-id: NWU5MDNlMTdfNzBiODJhMDlfZTVmMV8xNDAy****
x-cos-server-side-encryption-customer-algorithm: AES256
x-cos-server-side-encryption-customer-key-MD5: U5L61r7jcwdNvT7frmUG8g==



[Object Content]

Sample 8: downloading an object of the latest version (with versioning enabled)

Request

GET /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 10 Apr 2020 12:30:02 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1586521802;1586529002&q-key-time=1586521802;1586529002&q-header-list=date;host&q-url-param-list=&q-signature=****************************************
Connection: close

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 26
Connection: close
Accept-Ranges: bytes
Date: Fri, 10 Apr 2020 12:30:02 GMT
ETag: "22e024392de860289f0baa7d6cf8a549"
Last-Modified: Fri, 10 Apr 2020 12:29:52 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 11596229263574363878
x-cos-request-id: NWU5MDY2Y2FfMzFiYjBiMDlfMjE2NzVfMTgz****
x-cos-version-id: MTg0NDUxNTc1NTE5MTc1NjM4MDA



[Object Content Version 2]

Sample 9: downloading an object of a specific version (with versioning enabled)

Request

GET /exampleobject?versionId=MTg0NDUxNTc1NjIzMTQ1MDAwODg HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 10 Apr 2020 09:36:45 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1586511405;1586518605&q-key-time=1586511405;1586518605&q-header-list=date;host&q-url-param-list=versionid&q-signature=****************************************

Response

HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 16
Connection: close
Accept-Ranges: bytes
Date: Fri, 10 Apr 2020 09:36:45 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Last-Modified: Fri, 10 Apr 2020 09:36:35 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 16749565679157681890
x-cos-request-id: NWU5MDNlMmRfNzBiODJhMDlfZTYwZl8xM2Fh****
x-cos-version-id: MTg0NDUxNTc1NjIzMTQ1MDAwODg



[Object Content]

Sample 10: specifying the Range request header to download partial content

Request

GET /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Fri, 10 Apr 2020 12:32:37 GMT
Range: bytes=8-14
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1586521957;1586529157&q-key-time=1586521957;1586529157&q-header-list=date;host;range&q-url-param-list=&q-signature=****************************************
Connection: close

Response

HTTP/1.1 206 Partial Content
Content-Type: image/jpeg
Content-Length: 7
Connection: close
Accept-Ranges: bytes
Content-Range: bytes 8-14/16
Date: Fri, 10 Apr 2020 12:32:37 GMT
ETag: "ee8de918d05640145b18f70f4c3aa602"
Last-Modified: Fri, 10 Apr 2020 12:32:25 GMT
Server: tencent-cos
x-cos-hash-crc64ecma: 16749565679157681890
x-cos-request-id: NWU5MDY3NjVfY2VjODJhMDlfOWVlZl8xNmMy****



Content

Sample 11: downloading an ARCHIVE object that has not been restored

Request

GET /exampleobject HTTP/1.1
Host: examplebucket-1250000000.cos.ap-beijing.myqcloud.com
Date: Thu, 26 Dec 2019 11:57:24 GMT
Authorization: q-sign-algorithm=sha1&q-ak=************************************&q-sign-time=1577361444;1577368644&q-key-time=1577361444;1577368644&q-header-list=date;host&q-url-param-list=&q-signature=****************************************
Connection: close


Response

HTTP/1.1 403 Forbidden
Content-Type: application/xml
Content-Length: 513
Connection: close
Date: Thu, 26 Dec 2019 11:57:24 GMT
Server: tencent-cos
x-cos-request-id: NWUwNGEwMjRfZDcyNzVkNjRfNjZlM183Zjcx****
x-cos-storage-class: ARCHIVE



<?xml version='1.0' encoding='utf-8' ?>
<Error>
            <Code>InvalidObjectState</Code>
            <Message>The operation is not valid for the object storage class.</Message>
            <Resource>/exampleobject</Resource>
            <RequestId>NWUwNGEwMjRfZDcyNzVkNjRfNjZlM183Zjcx****</RequestId>
            <TraceId>OGVmYzZiMmQzYjA2OWNhODk0NTRkMTBiOWVmMDAxODc0OWRkZjk0ZDM1NmI1M2E2MTRlY2MzZDhmNmI5MWI1OTBjNjIyOGVlZmJlNDg4NDQ1MzAzMjA2ZDg4OGQ3MDhlMjIzYjI1ZWUwODY5YjdlMTBjY2EwNTgyZWMyMjc0Mjc=</TraceId>
</Error>


Previous Topic: HEAD ObjectNext Topic: DELETE Object

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback