List Objects

client.r2.buckets.objects.list(, , ?): CursorPagination<ObjectListResponse { custom_metadata, etag, http_metadata, 5 more } >

GET/accounts/{account_id}/r2/buckets/{bucket_name}/objects

Lists objects in an R2 bucket. Returns object metadata including key, size, etag, last modified date, HTTP metadata, and custom metadata.

For most workloads, we recommend using R2’s S3-compatible API or a Worker with an R2 binding instead.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

ParametersExpand Collapse

bucketName: string

Name of the bucket.

maxLength64

minLength3

params: ObjectListParams { account_id, cursor, delimiter, 4 more }

account_id: string

Path param: Account ID.

maxLength32

cursor?: string

Query param: Pagination cursor received from a previous List Objects call. Used to retrieve the next page of results.

delimiter?: string

Query param: A single character used to group keys. All keys that contain the delimiter between the prefix and the first occurrence of the delimiter after the prefix are grouped under a single result element.

per_page?: number

Query param: Maximum number of objects to return per page.

maximum1000

minimum1

prefix?: string

Query param: Restricts results to only those objects whose keys begin with the specified prefix.

start_after?: string

Query param: Returns objects with keys that come after the specified key in lexicographic order.

jurisdiction?: "default" | "eu" | "fedramp"

Header param: Jurisdiction where objects in this bucket are guaranteed to be stored.

One of the following:

"default"

"eu"

"fedramp"

ReturnsExpand Collapse

ObjectListResponse { custom_metadata, etag, http_metadata, 5 more }

Metadata for an R2 object.

custom_metadata?: Record<string, string>

Custom metadata key-value pairs associated with the object.

etag?: string

The entity tag for the object. In JSON list/get responses this is the raw hex digest (without surrounding quotes). The HTTP ETag response header on Get Object follows RFC 7232 and IS wrapped in surrounding double-quotes.

http_metadata?: HTTPMetadata { cacheControl, cacheExpiry, contentDisposition, 3 more }

HTTP metadata associated with an R2 object.

cacheControl?: string

Specifies caching behavior for the object.

cacheExpiry?: string

The date and time at which the object’s cache entry expires.

formatdate-time

contentDisposition?: string

Specifies presentational information for the object.

contentEncoding?: string

Specifies the content encoding applied to the object.

contentLanguage?: string

The language of the object content.

contentType?: string

The MIME type of the object.

key?: string

The object key (name).

last_modified?: string

The date and time the object was last modified.

formatdate-time

size?: number

The size of the object in bytes.

ssec?: boolean

Whether the object is encrypted with a customer-supplied encryption key.

storage_class?: "Standard" | "InfrequentAccess"

Storage class for newly uploaded objects, unless specified otherwise.

One of the following:

"Standard"

"InfrequentAccess"

List Objects

import Cloudflare from 'cloudflare';

const client = new Cloudflare({
  apiToken: process.env['CLOUDFLARE_API_TOKEN'], // This is the default and can be omitted
});

// Automatically fetches more pages as needed.
for await (const objectListResponse of client.r2.buckets.objects.list('example-bucket', {
  account_id: '023e105f4ecef8ad9ca31a8372d0c353',
})) {
  console.log(objectListResponse.custom_metadata);
}

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    "string"
  ],
  "result": [
    {
      "custom_metadata": {},
      "etag": "d41d8cd98f00b204e9800998ecf8427e",
      "http_metadata": {
        "cacheControl": "max-age=3600",
        "cacheExpiry": "2024-12-31T23:59:59Z",
        "contentDisposition": "attachment; filename=\"example.jpg\"",
        "contentEncoding": "gzip",
        "contentLanguage": "en-US",
        "contentType": "image/jpeg"
      },
      "key": "path/to/my-object.txt",
      "last_modified": "2024-01-15T10:30:00Z",
      "size": 1048576,
      "ssec": false,
      "storage_class": "Standard"
    }
  ],
  "success": true,
  "result_info": {
    "cursor": "eyJrZXkiOiJwYXRoL3RvL215LW9iamVjdC50eHQifQ==",
    "delimited": [
      "path/to/",
      "another/path/"
    ],
    "is_truncated": true,
    "per_page": 20
  }
}

Returns Examples

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    "string"
  ],
  "result": [
    {
      "custom_metadata": {},
      "etag": "d41d8cd98f00b204e9800998ecf8427e",
      "http_metadata": {
        "cacheControl": "max-age=3600",
        "cacheExpiry": "2024-12-31T23:59:59Z",
        "contentDisposition": "attachment; filename=\"example.jpg\"",
        "contentEncoding": "gzip",
        "contentLanguage": "en-US",
        "contentType": "image/jpeg"
      },
      "key": "path/to/my-object.txt",
      "last_modified": "2024-01-15T10:30:00Z",
      "size": 1048576,
      "ssec": false,
      "storage_class": "Standard"
    }
  ],
  "success": true,
  "result_info": {
    "cursor": "eyJrZXkiOiJwYXRoL3RvL215LW9iamVjdC50eHQifQ==",
    "delimited": [
      "path/to/",
      "another/path/"
    ],
    "is_truncated": true,
    "per_page": 20
  }
}