API Reference

R2

Buckets

Objects

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List Objects

client.R2.Buckets.Objects.List(ctx, bucketName, params) (*CursorPagination[BucketObjectListResponse], error)

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 BucketObjectListParams

AccountID param.Field[string]

Path param: Account ID.

maxLength32

Cursor param.Field[string]Optional

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

Delimiter param.Field[string]Optional

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.

PerPage param.Field[int64]Optional

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

maximum1000

minimum1

Prefix param.Field[string]Optional

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

StartAfter param.Field[string]Optional

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

Jurisdiction param.Field[BucketObjectListParamsCfR2Jurisdiction]Optional

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

const BucketObjectListParamsCfR2JurisdictionDefault BucketObjectListParamsCfR2Jurisdiction = "default"

const BucketObjectListParamsCfR2JurisdictionEu BucketObjectListParamsCfR2Jurisdiction = "eu"

const BucketObjectListParamsCfR2JurisdictionFedramp BucketObjectListParamsCfR2Jurisdiction = "fedramp"

ReturnsExpand Collapse

type BucketObjectListResponse struct{…}

Metadata for an R2 object.

CustomMetadata map[string, string]Optional

Custom metadata key-value pairs associated with the object.

Etag stringOptional

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.

HTTPMetadata BucketObjectListResponseHTTPMetadataOptional

HTTP metadata associated with an R2 object.

CacheControl stringOptional

Specifies caching behavior for the object.

CacheExpiry TimeOptional

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

formatdate-time

ContentDisposition stringOptional

Specifies presentational information for the object.

ContentEncoding stringOptional

Specifies the content encoding applied to the object.

ContentLanguage stringOptional

The language of the object content.

ContentType stringOptional

The MIME type of the object.

Key stringOptional

The object key (name).

LastModified TimeOptional

The date and time the object was last modified.

formatdate-time

Size int64Optional

The size of the object in bytes.

Ssec boolOptional

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

StorageClass BucketObjectListResponseStorageClassOptional

Storage class for newly uploaded objects, unless specified otherwise.

One of the following:

const BucketObjectListResponseStorageClassStandard BucketObjectListResponseStorageClass = "Standard"

const BucketObjectListResponseStorageClassInfrequentAccess BucketObjectListResponseStorageClass = "InfrequentAccess"

List Objects

Go

HTTP

TypeScript

Python

Go

Terraform

package main

import (
  "context"
  "fmt"

  "github.com/stainless-sdks/cloudflare-go"
  "github.com/stainless-sdks/cloudflare-go/option"
  "github.com/stainless-sdks/cloudflare-go/r2"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  page, err := client.R2.Buckets.Objects.List(
    context.TODO(),
    "example-bucket",
    r2.BucketObjectListParams{
      AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
    },
  )
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

200 example

{
  "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

200 example

{
  "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
  }
}