Help & Documentation>APIs>Cloud Object Storage>Object APIs>Basic Operations>GET Object

GET Object

Last updated: 2023-09-19 16:31:10

On this page:

Feature Overview

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 public-read (i.e., everyone can read it).
Note
If the response-* parameter is used in a request, anonymous access will not be supported and the request must carry a signature.
When configuring origin-pull through the COS console Set Origin without enabling Sync Origin, 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 (e.g., origin-pulling to an internal network address).


Versioning

With versioning enabled, you can specify the versionId request parameter to get a specific version of an object. If the version ID you specify corresponds to a delete marker, HTTP status code 404 (Not Found) will be returned. If no version ID is specified, the latest version will be 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.

Requests

Sample Request

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 more information, see Request Signature.)

Request Parameters

Name
Description
Local Disk Types
Required
response-cache-control
Sets the value of the Cache-Control header in the response
string
Not required
response-content-disposition
Sets the value of the Content-Disposition header in the response
string
Not required
response-content-encoding
Sets the value of the Content-Encoding header in the response
string
Not required
response-content-language
Sets the value of the Content-Language header in the response
string
Not required
response-content-type
Sets the value of the Content-Type header in the response
string
Not required
response-expires
Sets the value of the Expires header in the response
string
Not required
versionId
Specifies the version ID of the object (if versioning is enabled). If this parameter is not specified, the object of the latest version will be downloaded.
string
Not required

Request Header

In addition to common request headers, this API also supports the following request headers. For more information on the common request header, see Common Request Headers.
Name
Description
Local Disk Types
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.
For example, bytes=0-9 indicates downloading the first 10 bytes of the object; bytes=5-9 indicates downloading the 6th to the 10th byte of the object. In this case, the HTTP status code 206 (Partial Content) and the Content-Range response header are returned.
If the first value exceeds the object size, an HTTP status code 416 (Requested Range Not Satisfiable) error is returned. If not specified, the entire object will be downloaded.
string
Not required
If-Modified-Since
If the object is modified after the specified time, the object will be returned; otherwise, HTTP status code 304 (Not Modified) will be returned.
string
Not required
If-Unmodified-Since
If the object is not modified after the specified time, the object will be returned; otherwise, HTTP status code 412 (Precondition Failed) will be returned.
string
Not required
If-Match
If the ETag of the object is the same as the specified value, the object will be returned; otherwise, HTTP status code 412 (Precondition Failed) will be returned.
string
Not required
If-None-Match
If the ETag of the object is different from the specified value, the object will be returned; otherwise, HTTP status code 304 (Not Modified) will be returned.
string
Not required
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, i.e., 800 Kb/s to 800 Mb/s. If it exceeds this range, a 400 error will be returned.
integer
Not required
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 does not have a request body.

Response

Response Header

In addition to common response headers, this API also returns the following response headers. For more information on common response headers, see Common Response Headers.
Name
Description
Local Disk Types
Cache-Control
Cache directives as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.
string
Content-Disposition
Filename as defined in RFC 2616. It will be returned only if it is contained in the object metadata or specified through the request parameter.
string
Content-Encoding
Encoding format as defined in RFC 2616, which will be returned only if it is contained in the object metadata or if it is specified in the request parameter
string
Content-Range
Byte range of the returned content as defined in RFC 2616, which will be returned only if the Range request header is specified in the request
string
Expires
Cache expiration time as defined in RFC 2616, which will be returned only if it is contained in the object metadata or if it is specified in the request parameter
string
x-cos-meta-*
Includes user-defined metadata header suffixes and user-defined metadata information
string
x-cos-storage-class
Object storage type. For enumeration values, please refer to the Storage Types documentation, such as MAZ_STANDARD, MAZ_STANDARD_IA, INTELLIGENT_TIERING, MAZ_INTELLIGENT_TIERING, STANDARD_IA, ARCHIVE, and DEEP_ARCHIVE. This header will be returned only if the object is not STANDARD storage.
enum
x-cos-storage-tier
Specifies the access tier of INTELLIGENT TIERING objects. Valid values: FREQUENT, INFREQUENT
enum
Versioning-Related Headers
If the target object is from a versioning-enabled bucket, the following response header will be returned:
Name
Description
Local Disk Types
x-cos-version-id
Version ID of the 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 returns common error responses and error codes. For more information, see Error Codes.

Examples

Example 1: simple use case (with versioning disabled)

Requests

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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1586511316;1586518516&q-key-time=1586511316;1586518516&q-header-list=date;host&q-url-param-list=&q-signature=1bd1898e241fb978df336dc68aaef4c0acae**
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: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

Requests

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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&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=4fcea9f80bc67fe475dff746eca0b9abff6a**
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

Requests

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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1596005509;1596012709&q-key-time=1596005509;1596012709&q-header-list=date;host;if-none-match&q-url-param-list=&q-signature=20e39095b9f22ae1279bec2a3375b527c32d**
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

Requests

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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1596005510;1596012710&q-key-time=1596005510;1596012710&q-header-list=date;host;if-match&q-url-param-list=&q-signature=1437a0d094c4e0f8e26909d35b2cca83dcbf**
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

Requests

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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1586511360;1586518560&q-key-time=1586511360;1586518560&q-header-list=date;host&q-url-param-list=&q-signature=6f9ec1af1aa86abd5b484b41ae1378850ad2**
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

Requests

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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1586511371;1586518571&q-key-time=1586511371;1586518571&q-header-list=date;host&q-url-param-list=&q-signature=bdadbe917a50feeb8dddf8c75642be172720**
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

Requests

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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&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=7da5c304f9439df949b6550ab23aea67a5f0**
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)

Requests

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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1586521802;1586529002&q-key-time=1586521802;1586529002&q-header-list=date;host&q-url-param-list=&q-signature=51b3c33f4cfae5d7b31ad61a974db7374f39**
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)

Requests

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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1586511405;1586518605&q-key-time=1586511405;1586518605&q-header-list=date;host&q-url-param-list=versionid&q-signature=31aeb69334b973ef7406300a182de0645c91**
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: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

Requests

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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1586521957;1586529157&q-key-time=1586521957;1586529157&q-header-list=date;host;range&q-url-param-list=&q-signature=719273479357f4b4b4c7d4f5ceb631753101**
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

Requests

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=AKID8A0fBVtYFrNm02oY1g1JQQF0c3JO**&q-sign-time=1577361444;1577368644&q-key-time=1577361444;1577368644&q-header-list=date;host&q-url-param-list=&q-signature=d975dc7097b2dbffcf2ba001e6dec25dd80a**
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>examplebucket-1250000000.cos.ap-beijing.myqcloud.com/exampleobject</Resource>
            <RequestId>NWUwNGEwMjRfZDcyNzVkNjRfNjZlM183Zjcx****</RequestId>
            <TraceId>OGVmYzZiMmQzYjA2OWNhODk0NTRkMTBiOWVmMDAxODc0OWRkZjk0ZDM1NmI1M2E2MTRlY2MzZDhmNmI5MWI1OTBjNjIyOGVlZmJlNDg4NDQ1MzAzMjA2ZDg4OGQ3MDhlMjIzYjI1ZWUwODY5YjdlMTBjY2EwNTgyZWMyMjc0Mjc=</TraceId>
</Error>

中国站 - English