Workers API reference·续

Workers API reference·续

There are 3 variations of arguments that can be used in a range:

An offset with an optional length.
An optional offset with a length.
A suffix.
offset number
The byte to begin returning data from, inclusive.
length number
The number of bytes to return. If more bytes are requested than exist in the object, fewer bytes than this number may be returned.
suffix number
The number of bytes to return from the end of the file, starting from the last byte. If more bytes are requested than exist in the object, fewer bytes than this number may be returned.

R2PutOptions

onlyIf R2Conditional | Headers
Specifies that the object should only be stored given satisfaction of certain conditions in the R2Conditional. Refer to Conditional operations.
httpMetadata R2HTTPMetadata | Headers optional
Various HTTP headers associated with the object. Refer to HTTP Metadata.
customMetadata Record<string, string> optional
A map of custom, user-defined metadata that will be stored with the object.

Note

Only a single hashing algorithm can be specified at once.

md5 ArrayBuffer | string optional
A md5 hash to use to check the received object's integrity.
sha1 ArrayBuffer | string optional
A SHA-1 hash to use to check the received object's integrity.
sha256 ArrayBuffer | string optional
A SHA-256 hash to use to check the received object's integrity.
sha384 ArrayBuffer | string optional
A SHA-384 hash to use to check the received object's integrity.
sha512 ArrayBuffer | string optional
A SHA-512 hash to use to check the received object's integrity.
storageClass 'Standard' | 'InfrequentAccess'
Sets the storage class of the object if provided. Otherwise, the object will be stored in the default storage class associated with the bucket. Refer to Storage Classes.
ssecKey ArrayBuffer | string
Specifies a key to be used for SSE-C. Key must be 32 bytes in length, in the form of a hex-encoded string or an ArrayBuffer.

R2MultipartOptions

httpMetadata R2HTTPMetadata | Headers optional
Various HTTP headers associated with the object. Refer to HTTP Metadata.
customMetadata Record<string, string> optional
A map of custom, user-defined metadata that will be stored with the object.
storageClass string
Sets the storage class of the object if provided. Otherwise, the object will be stored in the default storage class associated with the bucket. Refer to Storage Classes.
ssecKey ArrayBuffer | string
Specifies a key to be used for SSE-C. Key must be 32 bytes in length, in the form of a hex-encoded string or an ArrayBuffer.

R2ListOptions

limit number optional
The number of results to return. Defaults to 1000, with a maximum of 1000.
If include is set, you may receive fewer than limit results in your response to accommodate metadata.
prefix string optional
The prefix to match keys against. Keys will only be returned if they start with given prefix.
cursor string optional
An opaque token that indicates where to continue listing objects from. A cursor can be retrieved from a previous list operation.
delimiter string optional
The character to use when grouping keys.
include Array<string> optional
Can include httpMetadata and/or customMetadata. If included, items returned by the list will include the specified metadata.
Note that there is a limit on the total amount of data that a single list operation can return. If you request data, you may receive fewer than limit results in your response to accommodate metadata.
The compatibility date must be set to 2022-08-04 or later in your Wrangler file. If not, then the r2_list_honor_include compatibility flag must be set. Otherwise it is treated as include: ['httpMetadata', 'customMetadata'] regardless of what the include option provided actually is.

This means applications must be careful to avoid comparing the amount of returned objects against your limit. Instead, use the truncated property to determine if the list request has more data to be returned.

const options = {
    limit: 500,
    include: ["customMetadata"],
};

const listed = await env.MY_BUCKET.list(options);

let truncated = listed.truncated;
let cursor = truncated ? listed.cursor : undefined;

// ❌ - if your limit can't fit into a single response or your
// bucket has less objects than the limit, it will get stuck here.
while (listed.objects.length < options.limit) {
    // ...
}

// ✅ - use the truncated property to check if there are more
// objects to be returned
while (truncated) {
    const next = await env.MY_BUCKET.list({
        ...options,
        cursor: cursor,
    });
    listed.objects.push(...next.objects);

truncated = next.truncated;
    cursor = next.cursor;
}

limit = 500
include = ["customMetadata"]

listed = await self.env.MY_BUCKET.list(limit=limit, include=include)

truncated = listed.truncated
cursor = listed.cursor if truncated else None

# ❌ - if your limit can't fit into a single response or your
# bucket has less objects than the limit, it will get stuck here.
while len(listed.objects) < limit:
    ...

# ✅ - use the truncated property to check if there are more
# objects to be returned
while truncated:
    next_page = await self.env.MY_BUCKET.list(limit=limit, include=include, cursor=cursor)
    listed.objects.extend(next_page.objects)

truncated = next_page.truncated
    cursor = next_page.cursor

R2Objects

An object containing an R2Object array, returned by BUCKET_BINDING.list().

objects Array<R2Object>
An array of objects matching the list request.
truncated boolean
If true, indicates there are more results to be retrieved for the current list request.
cursor string optional
A token that can be passed to future list calls to resume listing from that point. Only present if truncated is true.
delimitedPrefixes Array<string>
If a delimiter has been specified, contains all prefixes between the specified prefix and the next occurrence of the delimiter.
For example, if no prefix is provided and the delimiter is '/', foo/bar/baz would return foo as a delimited prefix. If foo/ was passed as a prefix with the same structure and delimiter, foo/bar would be returned as a delimited prefix.

Conditional operations

You can pass an R2Conditional object to R2GetOptions and R2PutOptions. If the condition check for get() fails, the body will not be returned. This will make get() have lower latency.

If the condition check for put() fails, null will be returned instead of the R2Object.

etagMatches string optional
Performs the operation if the object's etag matches the given string.
etagDoesNotMatch string optional
Performs the operation if the object's etag does not match the given string.
uploadedBefore Date optional
Performs the operation if the object was uploaded before the given date.
uploadedAfter Date optional
Performs the operation if the object was uploaded after the given date.

Alternatively, you can pass a Headers object containing conditional headers to R2GetOptions and R2PutOptions. For information on these conditional headers, refer to the MDN docs on conditional requests ↗︎. All conditional headers aside from If-Range are supported.

For more specific information about conditional requests, refer to RFC 7232 ↗︎.

HTTP Metadata

Generally, these fields match the HTTP metadata passed when the object was created. They can be overridden when issuing GET requests, in which case, the given values will be echoed back in the response.

contentType string optional
contentLanguage string optional
contentDisposition string optional
contentEncoding string optional
cacheControl string optional
cacheExpiry Date optional

Checksums

If a checksum was provided when using the put() binding, it will be available on the returned object under the checksums property. The MD5 checksum will be included by default for non-multipart objects.

md5 ArrayBuffer optional
The MD5 checksum of the object.
sha1 ArrayBuffer optional
The SHA-1 checksum of the object.
sha256 ArrayBuffer optional
The SHA-256 checksum of the object.
sha384 ArrayBuffer optional
The SHA-384 checksum of the object.
sha512 ArrayBuffer optional
The SHA-512 checksum of the object.

`R2UploadedPart`

An R2UploadedPart object represents a part that has been uploaded. R2UploadedPart objects are returned from uploadPart operations and must be passed to completeMultipartUpload operations.

partNumber number
The number of the part.
etag string
The etag of the part.

Storage Class

The storage class where an R2Object is stored. The available storage classes are Standard and InfrequentAccess. Refer to Storage classes for more information.

Was this helpful?

YesNo

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/r2/api/workers/workers-api-reference/#page","headline":"Workers API reference","description":"Complete reference for the R2 in-Worker API, including bucket and object operations.","url":"https://developers.cloudflare.com/r2/api/workers/workers-api-reference/","inLanguage":"en","image":"https://developers.cloudflare.com/r2/api/workers/workers-api-reference/og.png?v=c3d660cabeabbae1","dateModified":"2026-07-31","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Bind an R2 bucket to a Worker and perform read, write, and list operations. title: Use R2 from Workers image: https://developers.cloudflare.com/r2/api/workers/workers-api-usage/og.png?v=f165a52a3dcb3a35

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/r2/llms.txt
Use this file to discover all available pages before exploring further.

Workers API reference·续

Workers API reference·续

R2PutOptions

R2MultipartOptions

R2ListOptions

R2Objects

Conditional operations

HTTP Metadata

Checksums

R2UploadedPart

Storage Class

On this page

`R2UploadedPart`