List Buckets

r2.buckets.list() -> BucketListResponse

GET/accounts/{account_id}/r2/buckets

Lists a page of R2 buckets in the account and selected jurisdiction. Use the returned cursor to retrieve the next page.

Security

API Token

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

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

Accepted Permissions (at least one required)

Workers R2 Storage WriteWorkers R2 Storage Read

ParametersExpand Collapse

account_id: str

Cloudflare account ID that owns the R2 resource.

maxLength32

cursor: Optional[str]

Pagination cursor received during the last List Buckets call. R2 buckets are paginated using cursors instead of page numbers.

direction: Optional[Literal["asc", "desc"]]

Direction to order buckets.

One of the following:

"asc"

"desc"

name_contains: Optional[str]

Bucket names to filter by. Only buckets with this phrase in their name will be returned.

order: Optional[Literal["name"]]

Field to order buckets by.

per_page: Optional[float]

Maximum number of buckets to return in a single call.

maximum1000

minimum1

start_after: Optional[str]

Bucket name to start searching after. Buckets are ordered lexicographically.

cf_r2_jurisdiction: Optional[Literal["default", "eu", "us", 2 more]]

One of the following:

"default"

"eu"

"us"

"fedramp"

"fedramp-high"

ReturnsExpand Collapse

class BucketListResponse: …

buckets: Optional[List[Bucket]]

creation_date: Optional[str]

Creation timestamp.

jurisdiction: Optional[Literal["default", "eu", "us", 2 more]]

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

One of the following:

"default"

"eu"

"us"

"fedramp"

"fedramp-high"

location: Optional[Literal["apac", "eeur", "enam", 3 more]]

Location of the bucket.

One of the following:

"apac"

"eeur"

"enam"

"weur"

"wnam"

"oc"

name: Optional[str]

Name of the bucket.

maxLength64

minLength3

storage_class: Optional[Literal["Standard", "InfrequentAccess"]]

Storage class for newly uploaded objects, unless specified otherwise.

One of the following:

"Standard"

"InfrequentAccess"

List Buckets

import os
from cloudflare import Cloudflare

client = Cloudflare(
    api_token=os.environ.get("CLOUDFLARE_API_TOKEN"),  # This is the default and can be omitted
)
buckets = client.r2.buckets.list(
    account_id="023e105f4ecef8ad9ca31a8372d0c353",
)
print(buckets.buckets)

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    "string"
  ],
  "result": {
    "buckets": [
      {
        "creation_date": "creation_date",
        "jurisdiction": "default",
        "location": "apac",
        "name": "example-bucket",
        "storage_class": "Standard"
      }
    ]
  },
  "success": true,
  "result_info": {
    "cursor": "1-JTdCJTIydiUyMiUzQTElMkMlMjJzdGFydEFmdGVyJTIyJTNBJTIyZGF2aWRwdWJsaWMlMjIlN0Q=",
    "per_page": 20
  }
}

Returns Examples

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    "string"
  ],
  "result": {
    "buckets": [
      {
        "creation_date": "creation_date",
        "jurisdiction": "default",
        "location": "apac",
        "name": "example-bucket",
        "storage_class": "Standard"
      }
    ]
  },
  "success": true,
  "result_info": {
    "cursor": "1-JTdCJTIydiUyMiUzQTElMkMlMjJzdGFydEFmdGVyJTIyJTNBJTIyZGF2aWRwdWJsaWMlMjIlN0Q=",
    "per_page": 20
  }
}