All Products
Search

This Product

    Object Storage Service:GetObject

    Document Center

    Object Storage Service:GetObject

    Last Updated:Oct 21, 2025

    The GetObject operation retrieves an object from a bucket. To call this operation, you must have read permissions for the object.

    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 download large files (larger than 100 MB) from OSS, the transfer may fail due to network issues. You can use HTTP Range requests to retrieve parts of a large file. This enables resumable and concurrent downloads and improves 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. You can specify multiple byte ranges in a single request to improve download efficiency.

    • To allow access only via HTTPS, you can use a bucket policy to grant access.

    • If the object is in the Archive storage class, you must first send a RestoreObject request or enable real-time access of Archive objects for the bucket where the object is stored.

    Permissions

    By default, an Alibaba Cloud account has full permissions for resources in the account. RAM users or RAM roles under an Alibaba Cloud account have no permissions by default. The Alibaba Cloud account or an administrator must grant operation permissions to them using a RAM Policy or a Bucket policies.

    API

    Action

    Definition

    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 specified version is returned. If you set versionId to null, the version with a null versionId is returned.

    API behavior

    • The GetObject operation is compatible with standard RFC protocols.

    • Multi-range download is supported. You can download multiple ranges of an object at a time.

      • A multi-range download request is triggered only if the request includes the x-oss-multi-range-behavior: multi-range request header.

      • The maximum number of range intervals is 50.

    Billing and throttling

    • When you use the multi-range feature, the number of GetObject API calls for billing is calculated as follows: Number of API calls × Number of range shards per call.

    • The same logic applies to throttling. The number of GetObject API calls for throttling is calculated as follows: Number of API calls × Number of range shards per call.

    Request parameters

    Request headers

    You can use request headers in a GET request to customize response headers. The response headers are set to the values specified in the GET request headers only if the request is successful (the return code is 200 OK).

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

    Name

    Type

    Required

    Description

    Range

    String

    No

    The range of the file to transfer.

    • If the specified range is valid, the response message includes the total size of the object and the range of the object returned for the current request. For example, Content-Range: bytes 0-9/44 indicates that the total size of the object is 44 bytes and the range returned is 0-9.

    • If the specified range is invalid, the entire object is transferred, and the response does not include Content-Range.

    • When you use x-oss-multi-range-behavior: multi-range, you can specify multiple ranges. For example: Range: bytes=0-1,3-4,5-6,7-8. A maximum of 50 range intervals are supported.

    Default: none.

    x-oss-multi-range-behavior

    String

    No

    Enables the multi-range download feature.

    • If you set this header to multi-range, you can specify multiple byte ranges in the Range header for download.

    • If the specified range is invalid, the entire object is transferred.

    • When you use multi-range download, the number of API calls for billing and throttling = Actual number of calls × Number of range shards.

    Default: none.

    If-Modified-Since

    String

    No

    If the specified time is earlier than the actual modification time of the object or 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, 304 Not Modified is returned.

    Format: GMT. Example: Fri, 13 Nov 2015 14:47:53 GMT

    Default: 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 200 OK is returned. If the specified time is earlier than the actual modification time, 412 Precondition Failed 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: none.

    If-Match

    String

    No

    If the ETag you provide matches the ETag of the object, the object is transferred and 200 OK is returned. If the ETag you provide does not match the ETag of the object, 412 Precondition Failed 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: none.

    If-None-Match

    String

    No

    If the ETag you provide does not match the ETag of the object, the object is transferred and 200 OK is returned. If the ETag you provide matches the ETag of the object, 304 Not Modified is returned.

    You can use If-Match and If-None-Match at the same time.

    Default: none.

    Accept-Encoding

    String

    No

    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 determines whether to compress the data using Gzip during transfer based on the Content-Type and size (at least 1 KB) of the object. If the conditions are met, the data is transferred in compressed format. Otherwise, the data is transferred in its original format.

    • If Gzip compression is used and takes effect, the ETag and Content-Length information is not included.

    • 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: none.

    Query parameters

    Name

    Type

    Required

    Description

    response-content-language

    String

    No

    Specifies the content-language header that OSS returns for the request.

    Default: none.

    response-expires

    String

    No

    Specifies the expires header that OSS returns for the request.

    Default: none.

    response-cache-control

    String

    No

    Specifies the cache-control header that OSS returns for the request.

    Default: none.

    response-content-disposition

    String

    No

    Specifies the content-disposition header that OSS returns for the request.

    Default: none.

    response-content-encoding

    String

    No

    Specifies the content-encoding header that OSS returns for the request.

    Default: none.

    Response parameters

    Response headers

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

    Name

    Type

    Description

    x-oss-server-side-encryption

    String

    If the object is stored with server-side encryption, the object is automatically decrypted and returned when you send a GET request. The x-oss-server-side-encryption header is returned in the response to indicate the server-side encryption algorithm of the object.

    x-oss-sealed-time

    String

    If the object is an appendable object on which the Seal operation has been performed, this header is returned to indicate the time when the Seal operation was performed on the file. The value is similar to Sat, 11 Oct 2025 06:41:42 GMT.

    x-oss-tagging-count

    String

    The number of tags associated with the object. This header is returned only if you have the permissions to read tags.

    x-oss-expiration

    String

    The expiration time of an object in a bucket for which a lifecycle rule is configured.

    • The bucket has versioning enabled

      • A request is sent without a versionId

        If the requested object hits a delete rule in the lifecycle, the x-oss-expiration header is returned in the response to indicate the expiration time of the current version of the object.

      • A request is sent with a versionId

        The x-oss-expiration header is not returned in the response, regardless of whether the requested object hits a delete rule in the lifecycle.

    • The bucket does not have versioning enabled

      • If the requested object hits a delete rule in the lifecycle, the x-oss-expiration header is returned in the response.

      • If the requested object does not hit a delete rule in the lifecycle, the x-oss-expiration header is not returned in the response.

    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 (when the object is a file)

      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/jpg
Content-Length: 344606
Server: AliyunOSS
[344606 bytes of object data]

    • Sample response (when the object is a folder)

      When the object is a folder, custom response headers such as Range in the request are invalid.

      HTTP/1.1 200 OK
x-oss-request-id: 3a8f-2e2d-7965-3ff9-51c875b*****
x-oss-object-type: Normal
Date: Wed, 31 Mar 2021 06:38:30 GMT
Last-Modified: Tue, 30 Mar 2021 06:07:48 GMT
ETag: "null"
Content-Type: application/x-directory
Content-Length: 0
Server: AliyunOSS

    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/jpg
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=Chinese 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: Chinese
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/jpg
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 the error codes for this operation.

    Error code

    HTTP status code

    Description

    NoSuchKey

    404

    The target 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

    When you download an object of the Archive storage class:

    • A RestoreObject request was not submitted, or the last submitted RestoreObject request has timed out.

    • A RestoreObject request has been submitted, but the restore operation is not yet complete.

    Not Modified

    304

    This error is 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 is returned for the following reasons:

    • The If-Unmodified-Since header is specified, but the specified time is earlier than the actual modification time of the object.

    • The If-Match header is specified, but the ETag of the requested object is not the same as the provided ETag.

    Not Found

    404

    This error is returned if the versionId of an object is not specified in the request and the current version of the object is a delete marker.

    Method Not Allowed

    405

    This error is returned if the versionId of an object is specified in the request and the versionId corresponds to a delete marker.

    Integration methods