Object Storage Service (OSS) GetObject API-Object Storage Service(OSS)-阿里云帮助中心

The GetObject operation downloads an object from a bucket. You must have read permissions for the object to call this operation.

Request syntax

GET /ObjectName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Range: bytes=ByteRange (Optional)

For information about how to calculate the signature for the Authorization header, see Authorization request header.
When you call this operation in an OSS on CloudBox environment, replace the Host with the CloudBox Endpoint. For more information, see CloudBox Endpoint.
When you download large objects (larger than 100 MB) from Object Storage Service (OSS), the transfer might fail due to network issues. You can use HTTP Range requests to retrieve a large object in parts. This method enables resumable and concurrent downloads, improving transfer reliability. For more information, see How to obtain OSS resources in segments using HTTP Range requests.

Usage notes

The GetObject operation supports access over HTTP and HTTPS by default. It also supports multi-range downloads, allowing you to specify multiple byte ranges in a single request to improve download efficiency.

To allow access only over HTTPS, use a bucket policy.
If the object is in the Archive storage class, you must first restore it by sending a RestoreObject request, or enable real-time access for the bucket where the object is stored.

Permissions

By default, an Alibaba Cloud account has full permissions on all resources that are owned by the account. However, RAM users and RAM roles do not have any permissions by default. The Alibaba Cloud account owner or an administrator must grant permissions to RAM users or RAM roles by using a RAM policy or a bucket policy.

API	Action	Description
GetObject	`oss:GetObject`	Downloads an object.
	`oss:GetObjectVersion`	When downloading an object, if you specify the object version through versionId, this permission is required.
	`kms:Decrypt`	When downloading an object, if the object metadata contains X-Oss-Server-Side-Encryption: KMS, this permission is required.

Versioning

By default, a call to the GetObject operation returns only the current version of an object. If you specify the versionId of an object in the query parameters, the operation returns the specified version. If you set versionId to null, the operation returns the version that has a null version ID.

API behavior

The GetObject operation is compatible with standard RFC protocols.
Multi-range download is supported, which allows you to download multiple ranges of an object in a single request.
- A multi-range download request is triggered only when the request includes the x-oss-multi-range-behavior: multi-range request header.
- You can specify a maximum of 50 range intervals.

Billing and throttling

For billing, a multi-range download is counted as multiple GetObject API calls, one for each range segment requested.
For throttling, the number of API calls is also calculated based on the number of range segments.

Request parameters

Request headers

OSS allows you to customize response headers in GET requests. OSS sets the response headers to the values you specify in the GET request, but only if the request succeeds with a 200 OK status code.

OSS does not support custom response headers in GET requests for anonymous access.

Parameter	Type	Required	Description
Range	String	No	Specifies the byte range of the object to download. If the specified range is valid, the response includes the total size of the object and the byte range returned. For example, `Content-Range: bytes 0-9/44` indicates that the object is 44 bytes in size, and the range returned is from byte 0 to 9. If the specified range is invalid, the entire object is returned, and the `Content-Range` header is not included in the response. When you set `x-oss-multi-range-behavior` to `multi-range`, you can specify multiple byte ranges. Example: `Range: bytes=0-1,3-4,5-6,7-8`. A maximum of 50 range intervals is supported. Default value: None
x-oss-multi-range-behavior	String	No	Enables multi-range downloads. Set this header to `multi-range` to specify multiple byte ranges in the `Range` header for download. If the specified range is invalid, the entire object is transferred. For billing and throttling, this request is counted as multiple calls, one for each range segment. Default value: None
If-Modified-Since	String	No	If the specified time is earlier than the actual modification time of the object, or if the specified time is invalid, the object is returned with a `200 OK` status. If the specified time is the same as or later than the actual modification time, a `304 Not Modified` status is returned. Format: GMT. Example: `Fri, 13 Nov 2015 14:47:53 GMT` Default value: None
If-Unmodified-Since	String	No	If the specified time is the same as or later than the actual modification time of the object, the object is transferred, and a `200 OK` status is returned. If the specified time is earlier than the actual modification time, a `412 Precondition Failed` status is returned. Format: GMT. Example: `Fri, 13 Nov 2015 14:47:53 GMT` You can use If-Modified-Since and If-Unmodified-Since at the same time. Default value: None
If-Match	String	No	If the ETag you provide matches the ETag of the object, the object is transferred, and a `200 OK` status is returned. If the ETag you provide does not match the ETag of the object, a `412 Precondition Failed` status is returned. The ETag of an object is used to check whether the data has changed. You can use the ETag value to verify data integrity. Default value: None
If-None-Match	String	No	If the ETag you provide does not match the ETag of the object, the object is transferred, and a `200 OK` status is returned. If the ETag you provide matches the ETag of the object, a `304 Not Modified` status is returned. You can use If-Match and If-None-Match at the same time. Default value: None
Accept-Encoding	String	No	Specifies the encoding type of the client. To transfer the returned content in Gzip compressed format, you must explicitly add `Accept-Encoding:gzip` to the request header. OSS compresses an object with Gzip for transfer if it is at least 1 KB in size and its Content-Type is supported. Otherwise, OSS transfers the object uncompressed. When an object is transferred with Gzip compression, the response does not include the ETag or `Content-Length` headers. OSS supports Gzip compression for data of the following `Content-Type` types: text/cache-manifest, text/xml, text/css, text/html, text/plain, application/javascript, application/x-javascript, application/rss+xml, application/json, text/json. Default value: None

Query parameters

Parameter	Type	Required	Description
response-content-language	String	No	Specifies the `Content-Language` header for the response. Default value: None
response-expires	String	No	Specifies the `Expires` header for the response. Default value: None
response-cache-control	String	No	Specifies the `Cache-Control` header for the response. Default value: None
response-content-disposition	String	No	Specifies the `Content-Disposition` header for the response. Default value: None
response-content-encoding	String	No	Specifies the `Content-Encoding` header for the response. Default value: None

Response parameters

Response headers

If the object is a symbolic link, OSS returns the content of the target object. In the response headers, Content-Length, ETag, and Content-Md5 are the metadata of the target object. Last-Modified is the more recent of the modification times of the target object and the symbolic link. Other headers contain the metadata of the symbolic link.

Parameter	Type	Description
x-oss-server-side-encryption	String	If the object is stored with server-side encryption, OSS automatically decrypts and returns the object in a GET request. The `x-oss-server-side-encryption` header is returned in the response to indicate the server-side encryption algorithm used for the object.
x-oss-sealed-time	String	If the object is a sealed appendable object, this header indicates when the Seal operation was performed. Example: `Sat, 11 Oct 2025 06:41:42 GMT`.
x-oss-tagging-count	String	The number of tags associated with the object. This header is included only if you have permission to read tags.
x-oss-expiration	String	The expiration time of an object in a bucket for which a lifecycle rule is configured. If versioning is enabled for the bucket: If a request is sent without a versionId: If the requested object matches a lifecycle rule for deletion, the `x-oss-expiration` header is returned to indicate the expiration time of the object's current version. If a request is sent with a versionId: The `x-oss-expiration` header is not returned, regardless of whether the requested object matches a lifecycle rule for deletion. If versioning is not enabled for the bucket: If the requested object matches a lifecycle rule for deletion, the `x-oss-expiration` header is returned. If the requested object does not match a lifecycle rule for deletion, the `x-oss-expiration` header is not returned.
x-oss-object-worm-mode	String	The retention policy mode of the object. If the object has an object-level retention policy configured, the value is `COMPLIANCE`. This response header is returned only when ObjectWorm is enabled for the bucket, the caller has the `GetObjectRetention` permission, and the object has a retention policy configured.
x-oss-object-worm-retain-until-date	String	The object's retention expiration date, in ISO 8601 format. The object cannot be deleted or overwritten before this date. This header is included only when ObjectWorm is enabled for the bucket, the caller has the `GetObjectRetention` permission, and the object has a retention policy configured.

Examples

Basic download

Sample request

GET /oss.jpg HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 24 Feb 2012 06:38:30 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 3a8f-2e2d-7965-3ff9-51c875b*****
x-oss-object-type: Normal
Date: Fri, 24 Feb 2012 06:38:30 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "5B3C1A2E0563E1B002CC607C*****"
Content-Type: image/jpeg
Content-Length: 344606
Server: AliyunOSS
[344606 bytes of object data]

Range download

Sample request

GET /oss.jpg HTTP/1.1
Host:oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Feb 2012 05:38:42 GMT
Range: bytes=100-900
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 206 Partial Content
x-oss-request-id: 28f6-15ea-8224-234e-c0ce407*****
x-oss-object-type: Normal
Date: Fri, 28 Feb 2012 05:38:42 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "5B3C1A2E05E1B002CC607C*****"
Accept-Ranges: bytes
Content-Range: bytes 100-900/344606
Content-Type: image/jpeg
Content-Length: 801
Server: AliyunOSS
[801 bytes of object data]

Multi-range download

Sample request

GET /oss.jpg HTTP/1.1
Host:oss-example.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Feb 2012 05:38:42 GMT
Range: bytes=0-1,3-4,5-6,7-8
x-oss-multi-range-behavior: multi-range
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 206 Partial Content
x-oss-request-id: 28f6-15ea-8224-234e-c0ce407*****
x-oss-object-type: Normal
Date: Fri, 28 Feb 2012 05:38:42 GMT
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "5B3C1A2E05E1B002CC607C*****"
Accept-Ranges: bytes
Content-Type: multipart/byteranges;boundary=63ce7776-c104-417f-8a65-ccaa3b17f428
Content-Length: 446
Server: AliyunOSS

--63ce7776-c104-417f-8a65-ccaa3b17f428
Content-type: text/plain
Content-range: bytes 0-1/10

[ 2 Bytes object content]
--63ce7776-c104-417f-8a65-ccaa3b17f428
Content-type: text/plain
Content-range: bytes 3-4/10

[ 2 Bytes object content]
--63ce7776-c104-417f-8a65-ccaa3b17f428
Content-type: text/plain
Content-range: bytes 5-6/10

[ 2 Bytes object content]
--63ce7776-c104-417f-8a65-ccaa3b17f428
Content-type: text/plain
Content-range: bytes 7-8/10

[ 2 Bytes object content]
--63ce7776-c104-417f-8a65-ccaa3b17f428--

Custom response headers

Sample request

GET /oss.jpg?response-expires=Thu%2C%2001%20Feb%202012%2017%3A00%3A00%20GMT&response-cache-control=No-cache&response-content-disposition=attachment%253B%2520filename%253Dtesting.txt&response-content-encoding=utf-8&response-content-language=%E4%B8%AD%E6%96%87 HTTP/1.1
Host: oss-example.oss-cn-hangzhou.aliyuncs.com:
Date: Fri, 24 Feb 2012 06:09:48 GMT

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 559CC9BDC75A644*****
x-oss-object-type: Normal
Date: Fri, 24 Feb 2012 06:09:48 GMT 
Last-Modified: Fri, 24 Feb 2012 06:07:48 GMT
ETag: "5B3C1A2E053D1B002CC607*****"
Content-Length: 344606
Connection: keep-alive
Content-disposition: attachment; filename=testing.txt
Content-language: 中文
Content-type: jpg
Cache-control: no-cache
Expires: Fri, 24 Feb 2012 17:00:00 GMT
Server: AliyunOSS
[344606 bytes of object data]

Symbolic link object

Sample request

GET /link-to-oss.jpg HTTP/1.1
Accept-Encoding: identity
Date: Tue, 08 Nov 2016 03:17:58 GMT
Host: oss-example.oss-cn-hangzhou.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 200 OK
Server: AliyunOSS
Date: Tue, 08 Nov 2016 03:17:58 GMT
Content-Type: application/octet-stream
Content-Length: 20
Connection: keep-alive
x-oss-request-id: 582143E6A212AD*****
Accept-Ranges: bytes
ETag: "8086265EFC021F9A2F09BF4****"
Last-Modified: Tue, 08 Nov 2016 03:17:58 GMT
x-oss-object-type: Symlink
Content-MD5: gIYmXvwCEe0fmi8Jv0Y****

Archive object (restored)

Sample request

GET /oss.jpg HTTP/1.1
Host: oss-archive-example.oss-cn-hangzhou.aliyuncs.com
Date: Sat, 15 Apr 2017 09:38:30 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 58F723829F29F18D7F00*****
x-oss-object-type: Normal
x-oss-restore: ongoing-request="false", expiry-date="Sun, 16 Apr 2017 08:12:33 GMT"
Date: Sat, 15 Apr 2017 09:38:30 GMT
Last-Modified: Sat, 15 Apr 2017 06:07:48 GMT
ETag: "5B3C1A2E0763E1B002CC607C*****"
Content-Type: image/jpeg
Content-Length: 344606
Server: AliyunOSS
[344606 bytes of object data]

Versioning scenarios

Specify a version ID

Sample request

GET /example?versionId=CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0**** HTTP/1.1
Host: versioning-get.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 09 Apr 2019 02:58:06 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 200 OK
x-oss-request-id: 5CAC0A3EDE0170*****
x-oss-version-id: CAEQNhiBgM0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY*****
x-oss-object-type: Normal
Date: Tue, 17 Apr 2025 02:58:06 GMT
Last-Modified: Fri, 22 Mar 2018 08:07:50 GMT
ETag: "5B3C1A2E053D7002CC607C5A*****"
Content-Type: text/html
Content-Length: 362149
Server: AliyunOSS
[362149 bytes of object data]

The current version is a delete marker

Sample request

GET /example HTTP/1.1
Host: versioning-get.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 17 Apr 2025 03:22:33 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 404 Not Found
x-oss-request-id: 5CAC0FEADE0170*****
x-oss-delete-marker: true
x-oss-version-id: CAEQNxiBgyA0BYiIDc4ZDdmNTA2MGViZTRiNjE5NzZlZWM4OWM5OT*****
Date: Tue, 17 Apr 2025 03:22:33 GMT
Content-Type: application/xml
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
  <RequestId>5CAC0FEADE0170*****</RequestId>
  <HostId>versioning-get.oss-cn-hangzhou.aliyun*****</HostId>
  <Key>example</Key>
</Error>

Specify the version ID of a delete marker

Sample request

GET /example?versionId=CAEQMxiBgMCfqaWA0BYiIDliMWI4MGQ0MTVmMjQ3MmE5MDNlMmY4YmFkYTk3**** HTTP/1.1
Host: versioning-get.oss-cn-hangzhou.aliyuncs.com
Date: Tue, 17 Apr 2025 03:09:44 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

Sample response

HTTP/1.1 405 Method Not Allowed
x-oss-request-id: 5CAC0CF8DE01700*****
x-oss-delete-marker: true
x-oss-version-id: CAEQMxiBgMCfqaWADliMWI4MGQ0MTVmMjQ3MmE5MDNlMmY4YmFkYTk*****
Allow: DELETE
Date: Tue, 17 Apr 2025 03:09:44 GMT
Content-Type: application/xml
Content-Length: 318
Connection: keep-alive
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Code>MethodNotAllowed</Code>
  <Message>The specified method is not allowed against this resource.</Message>
  <RequestId>5CAC0CF8DE0170*****</RequestId>
  <HostId>versioning-get.oss-cn-hangzhou.aliyunc*****</HostId>
  <Method>GET</Method>
  <ResourceType>DeleteMarker</ResourceType>
</Error>

Error codes

If a request fails, OSS returns a response body that contains an error code. The following table lists some common error codes for this operation.

Error code	HTTP status code	Description
NoSuchKey	404	The specified object does not exist.
SymlinkTargetNotExist	404	The object is a symbolic link, and the target object does not exist.
InvalidTargetType	400	The object is a symbolic link, and the target object is also a symbolic link.
InvalidObjectState	403	This error is returned when you attempt to download an object of the Archive storage class under the following conditions: A `RestoreObject` request has not been submitted, or the restored copy of the object has expired. A `RestoreObject` request was submitted, but the object is still being restored.
Not Modified	304	This error can be returned for the following reasons: The If-Modified-Since request header is specified, but the requested object has not been modified after the specified time. The If-None-Match request header is specified, and the ETag of the requested object is the same as the provided ETag.
Precondition Failed	412	This error can be returned for the following reasons: The If-Unmodified-Since header is specified, and the object was modified after the specified time. The If-Match header is specified, and its value does not match the object's ETag.
Not Found	404	This error is returned if a `versionId` is not specified and the current version of the object is a delete marker.
Method Not Allowed	405	This error is returned if the specified `versionId` corresponds to a delete marker.

Integration methods

SDK
You can call the GetObject operation by using the following SDKs:
Java
Python V2
PHP V2
Go V2
C
C++
.NET
Android
iOS
Node.js
Browser.js
Ruby
Harmony
ossutil command-line tool
For information about the ossutil command that corresponds to the GetObject operation, see get-object.

Java	Python V2	PHP V2	Go V2	C
C++	.NET	Android	iOS	Node.js
Browser.js	Ruby	Harmony