Cloudflare Docs
R2
Cloudflare Docs
R2
Search icon (depiction of a magnifying glass)
GitHub icon
Visit R2 on GitHub
Set theme to dark (⇧+D)

R2

The in-Worker R2 API is accessed by binding an R2 bucket to a Worker. The Worker you write can expose external access to buckets via a route or manipulate R2 objects internally.

The R2 API includes some extensions and semantic differences from the S3 API. If you need S3 compatibility, consider using the S3-compatible API.

​​ Concepts

R2 organizes the data you store, called objects, into containers, called buckets. Buckets are the fundamental unit of performance, scaling, and access within R2.

​​ Create a binding

To bind your R2 bucket to your Worker, add the following to your wrangler.toml file. Update the binding property to a valid JavaScript variable identifier and bucket_name to the name of your R2 bucket:

[[r2_buckets]]

binding = 'MY_BUCKET' # <~ valid JavaScript variable name

bucket_name = '<YOUR_BUCKET_NAME>'

Within your Worker, your bucket binding is now available under the MY_BUCKET variable and you can begin interacting with it using the bucket methods described below.

​​ Bucket method definitions

The following methods are available on the bucket binding object injected into your code.

For example, to issue a PUT object request using the binding above:

export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		const key = url.pathname.slice(1);


		switch (request.method) {
			case 'PUT':
				await env.MY_BUCKET.put(key, request.body);
				return new Response(`Put ${key} successfully!`);


			default:
				return new Response(`${request.method} is not allowed.`, {
					status: 405,
					headers: {
						Allow: 'PUT',
					},
				});
		}
	},

};

  • head(keystring) Promise<R2Object|null>

    • Retrieves the R2Object for the given key containing only object metadata, if the key exists, and null if the key does not exist.

  • get(keystring, optionsR2GetOptionsoptional) Promise<R2ObjectBody|R2Object|null>

    • Retrieves the R2Object for the given key containing object metadata and the object body as a ReadableStream, if the key exists, and null if the key does not exist.
    • In the event that a precondition specified in options fails, get() returns an R2Object with body undefined.

  • put(keystring, valueReadableStream|ArrayBuffer|ArrayBufferView|string|null|Blob, optionsR2PutOptionsoptional) Promise<R2Object>

    • Stores the given value and metadata under the associated key. Once the write succeeds, returns an R2Object containing metadata about the stored Object.
    • R2 writes are strongly consistent. Once the Promise resolves, all subsequent read operations will see this key value pair globally.

  • delete(keystring) Promise<void>

    • Deletes the given value and metadata under the associated key. Once the delete succeeds, returns void.
    • R2 deletes are strongly consistent. Once the Promise resolves, all subsequent read operations will no longer see this key value pair globally.

  • list(optionsR2ListOptionsoptional) Promise<R2Objects|null>

    • Returns an R2Objects containing a list of R2Object contained within the bucket. By default, returns the first 1000 entries.

​​ R2Object definition

R2Object is created when you PUT an object into an R2 bucket. R2Object represents the metadata of an object based on the information provided by the uploader. Every object that you PUT into an R2 bucket will have an R2Object created.

  • keystring

    • The object’s key.

  • bodyReadableStream

    • The object’s value.

  • bodyUsedboolean

    • Whether the object’s value has been consumed or not.

  • arrayBuffer()Promise<ArrayBuffer>

    • Returns a Promise that resolves to an ArrayBuffer containing the object’s value.

  • text()Promise<string>

    • Returns a Promise that resolves to an string containing the object’s value.

  • json()Promise<T>

    • Returns a Promise that resolves to the given object containing the object’s value.

  • blob()Promise<Blob>

    • Returns a Promise that resolves to a binary Blob containing the object’s value.

  • versionstring

    • Random unique string associated with a specific upload of a key.

  • sizenumber

    • Size of the object in bytes.

  • etagstring

    • The etag associated with the object upload.

  • httpEtagstring

    • The object’s etag, in quotes so as to be returned as a header.

  • uploadedDate

    • A Date object representing the time the object was uploaded.

  • httpMetadataR2HTTPMetadata

    • Various HTTP headers associated with the object. Refer to HTTP Metadata.

  • customMetadataRecord<string, string>

    • A map of custom, user-defined metadata associated with the object.

  • range R2Range

    • A R2Range object containing the returned range of the object.

  • writeHttpMetadata(headersHeaders) void

    • Retrieves the httpMetadata from the R2Object and applies their corresponding HTTP headers to the Headers input object. Refer to HTTP Metadata.

​​ Method-specific types

​​ R2GetOptions

  • onlyIfR2Conditional

    • Specifies that the object should only be returned given satisfaction of certain conditions in the R2Conditional. Refer to Conditional operations.

  • rangeR2Range

    • Specifies that only a specific length (from an optional offset) or suffix of bytes from the object should be returned. Refer to Ranged reads.

​​ Ranged reads

R2GetOptions accepts a range parameter, which can be used to restrict the data returned in body.

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.

  • offsetnumber

    • The byte to begin returning data from, inclusive.

  • lengthnumber

    • The number of bytes to return. If more bytes are requested than exist in the object, fewer bytes than this number may be returned.

  • suffixnumber

    • 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

  • httpMetadataR2HTTPMetadata|Headersoptional

    • Various HTTP headers associated with the object. Refer to HTTP Metadata.

  • customMetadataRecord<string, string>optional

    • A map of custom, user-defined metadata that will be stored with the object.

  • md5ArrayBuffer|stringoptional

    • A md5 hash to use to check the received object’s integrity.

​​ R2ListOptions

  • limitnumberoptional

    • The number of results to return. Defaults to 1000, with a maximum of 1000.

  • prefixstringoptional

    • The prefix to match keys against. Keys will only be returned if they start with given prefix.

  • cursorstringoptional

    • An opaque token that indicates where to continue listing objects from. A cursor can be retrieved from a previous list operation.

  • delimiterstringoptional

    • The character to use when grouping keys.

  • includeArray<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 recieve fewer than limit results in your response to accomodate metadata.

    • The compatibility date must be set to 2022-08-04 or later in your wrangler.toml file. If not, then the r2_list_honor_include compatibility flag must be set. Otherwise, it is treated as include: ['httpMetadata', 'customMetadata'] regardless of the include option provided.

    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.

index.js
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
}

​​ R2Objects

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

  • objectsArray<R2Object>

    • An array of objects matching the list request.

  • truncatedboolean

    • If true, indicates there are more results to be retrieved for the current list request.

  • cursorstringoptional

    • A token that can be passed to future list calls to resume listing from that point. Only present if truncated is true.

  • delimitedPrefixesArray<string>

    • If a delimiter has been specified, contains all prefixes between the specified prefix and the next occurence 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. If the condition check fails, the body will not be returned. This will make get() have lower latency.

  • etagMatchesstringoptional

    • Performs the operation if the object’s etag matches the given string.

  • etagDoesNotMatchstringoptional

    • Performs the operation if the object’s etag does not match the given string.

  • uploadedBeforeDateoptional

    • Performs the operation if the object was uploaded before the given date.

  • uploadedAfterDateoptional

    • Performs the operation if the object was uploaded after the given date.

For more 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.

  • contentTypestringoptional

  • contentLanguagestringoptional

  • contentDispositionstringoptional

  • contentEncodingstringoptional

  • cacheControlstringoptional

  • cacheExpiryDateoptional