List Buckets

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

Path ParametersExpand Collapse

account_id: string

Cloudflare account ID that owns the R2 resource.

maxLength32

Query ParametersExpand Collapse

cursor: optional string

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

direction: optional "asc" or "desc"

Direction to order buckets.

One of the following:

"asc"

"desc"

name_contains: optional string

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

order: optional "name"

Field to order buckets by.

per_page: optional number

Maximum number of buckets to return in a single call.

maximum1000

minimum1

start_after: optional string

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

Header ParametersExpand Collapse

"cf-r2-jurisdiction": optional "default" or "eu" or "us" or 2 more

One of the following:

"default"

"eu"

"us"

"fedramp"

"fedramp-high"

ReturnsExpand Collapse

errors: array of ResponseInfo { code, message, documentation_url, source }

code: number

minimum1000

message: string

documentation_url: optional string

source: optional object { pointer }

pointer: optional string

messages: array of string

result: object { buckets }

buckets: optional array of Bucket { creation_date, jurisdiction, location, 2 more }

creation_date: optional string

Creation timestamp.

jurisdiction: optional "default" or "eu" or "us" or 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 "apac" or "eeur" or "enam" or 3 more

Location of the bucket.

One of the following:

"apac"

"eeur"

"enam"

"weur"

"wnam"

"oc"

name: optional string

Name of the bucket.

maxLength64

minLength3

storage_class: optional "Standard" or "InfrequentAccess"

Storage class for newly uploaded objects, unless specified otherwise.

One of the following:

"Standard"

"InfrequentAccess"

success: true

Whether the API call was successful.

result_info: optional object { cursor, per_page }

cursor: optional string

A continuation token that should be used to fetch the next page of results.

per_page: optional number

Maximum number of results on this page.

List Buckets

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/r2/buckets \
    -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

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