S3 · Objects
GetObject
/{bucket}/{key}Reads an object.
Returns the bytes of the object with its stored headers. Send a Range header to read part of the object.
- Role
- Viewer or higher
- Support
- Partial
- Supports versionId, conditions, and one byte range. Multiple ranges return 501. A public-read bucket needs no signature.
- An unsigned GET works on a bucket with the public-read permission.
- A presigned URL works. See Authentication & keys.
- Storage ignores
partNumberand theresponse-*query parameters, such asresponse-content-type.
Path parameters
Query parameters
Read this version. Without it, storage reads the current version.
Headers
One byte range, for example bytes=0-1023. More than one range returns 501 NotImplemented.
Return the object only when its ETag matches. Otherwise, storage returns 412 PreconditionFailed.
Return 304 Not Modified when the ETag matches. Use it to revalidate a cached copy.
An HTTP date. Return 304 Not Modified when the object did not change after it. Storage ignores it when you send If-None-Match.
An HTTP date. Return 412 PreconditionFailed when the object changed after it. Storage ignores it when you send If-Match.
The workspace ID that must own the bucket. Another owner returns 403 AccessDenied.
Responses
200OK
The whole object.
The stored Content-Type
Response headers
ETagstringThe entity tag of the object, in double quotes.
Content-TypestringThe media type that the write stored.
Content-LengthintegerThe size of the object in bytes.
Last-ModifiedstringWhen the version was written, as an HTTP date.
Accept-RangesstringAlways bytes.
x-amz-version-idstringThe version ID of the object. Storage gives every write a version ID.
Each header that the write stored. When the object has a Content-Encoding, Cache-Control also has no-transform, so the bytes arrive as stored.
x-amz-checksum-*stringEach checksum that the write stored, such as x-amz-checksum-sha256.
The response body follows the content type above.
206Partial Content
The bytes in the Range. The response has no checksum headers, because they describe the whole object.
The stored Content-Type
Response headers
Content-RangestringThe range in the body and the full size, for example bytes 0-9/1024.
Content-LengthintegerThe size of the range in bytes.
ETagstringThe entity tag of the object, in double quotes.
x-amz-version-idstringThe version ID of the object. Storage gives every write a version ID.
The response body follows the content type above.
304Not Modified
If-None-Match or If-Modified-Since matched. The response has no body.
Response headers
ETagstringThe entity tag of the object, in double quotes.
x-amz-version-idstringThe version ID of the object. Storage gives every write a version ID.
This response has no body.
Errors
Select an error in the response example to see its XML body. Any request can also get the common errors, such as SignatureDoesNotMatch.
- 404NoSuchKey
The bucket has no object at this key, or no version with this versionId.
What to do: Check the key and the versionId.
- 404NoSuchBucket
No bucket has this name, or the bucket was deleted.
What to do: Check the bucket name. ListBuckets shows the buckets of the workspace.
- 403AccessDenied
The key does not have the Viewer role, or an unsigned request asked for a bucket that is not public-read.
What to do: Use a key of the workspace that owns the bucket, with the role above.
- 405MethodNotAllowed
The versionId names a delete marker, which has no bytes.
What to do: Use the versionId of a version that holds data. ListObjectVersions shows each one.
- 412PreconditionFailed
If-Match or If-Unmodified-Since did not hold.
What to do: Read the object again to get its current ETag, then decide whether to retry.
- 416InvalidRange
The range starts after the end of the object.
What to do: Read the size with HeadObject, then ask for a range inside it.
- 501NotImplemented
The Range header asks for more than one range.
What to do: Ask for one range in each request.