b2_list_buckets

11 Sep 2026

Print
Dark
Light

b2_list_buckets

Updated on 11 Sep 2026

Print
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

Post

/b2api/v4/b2_list_buckets

Lists buckets alphabetically by name

When using an authorization token that is restricted to a bucket, you must include the bucketId or bucketName of that bucket in the request, or the request will be denied.

API Versions

v2: Remove application key workaround (Sept 13, 2018)

Listing buckets will always return all buckets, unless you ask for just one by specifying bucketName or bucketId. If you ask for all buckets and your application key is restricted to one bucket, the call is unauthorized.

v1: Workaround for existing applications and application keys (August 9, 2018)

When using an application key that is restricted to a bucket, a request to list all buckets will return just that one bucket instead of returning "unauthorized".

v1: Application keys (July 26, 2018)

New optional bucketName and bucketId parameters to b2_list_buckets provide a way to get information about just one bucket. This is useful when using an application key that allows access to only one bucket.

v1: Original release (September 22, 2015)

B2 Cloud Storage was released.

For information on all API versions, view our API changelog.

Header parameters

Authorization

stringRequired

An account authorization token, obtained from b2_authorize_account.

The token must have the listBuckets capability.

Body parameters

object

accountId

string Required

Your account ID.

ExampleACCOUNT_ID

bucketId

string

When bucketId is specified, the result will be a list containing just this bucket, if it's present in the account, or no buckets if the account does not have a bucket with this ID.

Example4a48fe8875c6214145260818

bucketName

string

When bucketName is specified, the result will be a list containing just this bucket, if it's present in the account, or no buckets if the account does not have a bucket with this name.

ExamplemyBucketName

bucketTypes

Array of string

If present, this will be used as a filter for bucket types returned in the list buckets response. If not present, only buckets with bucket types "allPublic", "allPrivate" and "snapshot" will be returned. A special filter value of ["all"] will return all bucket types.

If present, it must be in the form of a json array of strings containing valid bucket types in quotes and separated by a comma. Valid bucket types include "allPrivate", "allPublic", "restricted", "snapshot", "shared", and other values added in the future.

A bad request error will be returned if "all" is used with other bucketTypes, bucketTypes is empty, or invalid bucketTypes are requested.

Example[ "allPublic", "allPrivate" ]

string

Responses

200

The request succeeded.

The response headers include the Content-Type that was specified when the file was uploaded. They also include the X-Bz-FileName and X-Bz-Content-Sha1 headers, plus X-Bz-Info-* headers for any custom file info that was provided with the upload. The X-Bz-FileName uses percent-encoding, as if it were a URL parameter.

Expand All

object

buckets

Array of object

An array of bucket objects.

Example[ { "accountId": "12f634bf3cbz", "bucketId": "4a48fe8875c6214145260818", "bucketInfo": {}, "bucketName": "Kitten-Videos", "bucketType": "allPrivate", "corsRules": [], "defaultServerSideEncryption": { "isClientAuthorizedToRead": true, "value": { "algorithm": "AES256", "mode": "SSE-B2" } }, "fileLockConfiguration": { "isClientAuthorizedToRead": true, "value": { "defaultRetention": { "mode": null, "period": null }, "isFileLockEnabled": true } }, "lifecycleRules": [], "options": [], "revision": 3 } ]

object

accountId

string

The account that the bucket is in.

bucketId

string

The unique identifier of the bucket.

Example3f46fe8276c62b414506021y

bucketName

string

The unique name of the bucket

bucketType

string

One of: allPublic, allPrivate, restricted, snapshot, shared, or other values added in the future. allPublic means that anybody can download the files is the bucket; allPrivate means that you need an authorization token to download them; snapshot means that it's a private bucket containing snapshots created in the Backblaze web UI.

bucketInfo

object

The user data stored with this bucket.

Example{}

corsRules

Array of object

The initial list (a JSON array) of CORS rules for this bucket. See CORS Rules for an overview and the rule structure.

Example[ { "corsRuleName": "downloadFromAnyOrigin", "allowedOrigins": [ "https" ], "allowedHeaders": [ "range" ], "allowedOperations": [ "b2_download_file_by_id", "b2_download_file_by_name" ], "exposeHeaders": [ "x-bz-content-sha1" ], "maxAgeSeconds": 3600 } ]

object

corsRuleName

string

ExampledownloadFromAnyOrigin

allowedOrigins

Array of string

Example[ "https" ]

string

allowedHeaders

Array of string

Example[ "range" ]

string

allowedOperations

Array of string

Example[ "b2_download_file_by_id", "b2_download_file_by_name" ]

string

exposeHeaders

Array of string

Example[ "x-bz-content-sha1" ]

string

maxAgeSeconds

integer

Example3600

fileLockConfiguration

object

The Object Lock configuration for this bucket. This field is filtered based on application key capabilities; readBucketRetentions capability is required to access the value. See Object Lock for more details on response structure.

isClientAuthorizedToRead

boolean

value

object

defaultRetention

object

mode

string

period

string

isFileLockEnabled

boolean

defaultServerSideEncryption

object

The effective default server-side encryption settings for new files uploaded to this bucket. For callers with readBucketEncryption, value is SSE-B2 with AES256 even when the bucket has no stored encryption configuration. For callers without that capability, isClientAuthorizedToRead is false and value is null. A filtered null value does not indicate that encryption is disabled.

Example{ "isClientAuthorizedToRead": true, "value": { "algorithm": "AES256", "mode": "SSE-B2" } }

isClientAuthorizedToRead

boolean

Exampletrue

value

object

algorithm

string

ExampleAES256

mode

string

ExampleSSE-B2

lifecycleRules

object

The list of lifecycle rules for this bucket. See Lifecycle Rules for an overview and the rule structure.

Example{ "daysFromHidingToDeleting": 30, "daysFromUploadingToHiding": null, "fileNamePrefix": "backup/" }

daysFromHidingToDeleting

integer

daysFromUploadingToHiding

integer

fileNamePrefix

string

replicationConfiguration

object

The list of replication rules for this bucket. See Cloud Replication Rules for an overview and the rule structure.

NOTE: The first time that you configure Cloud Replication, complete the following tasks to ensure that you have the correct permission:

Verify your email address.
Have a payment history on file or make a payment.

Example{ "asReplicationSource": { "replicationRules": [ { "destinationBucketId": "3f46fe8276c62b414506021y", "fileNamePrefix": "", "includeExistingFiles": false, "isEnabled": true, "priority": 1, "replicationRuleName": "replication-us-east" } ], "sourceApplicationKeyId": "00512f95cf4dcf0000000004z" } }

asReplicationSource

object

replicationRules

Array of object

object

destinationBucketId

string

Example3f46fe8276c62b414506021y

fileNamePrefix

string

Example

includeExistingFiles

boolean

Examplefalse

isEnabled

boolean

Exampletrue

priority

integer

Example1

replicationRuleName

string

Examplereplication-us-east

asReplicationDestination

object

sourceToDestinationKeyMapping

string

Example00512f95cf4dcf0000000004y

revision

integer

A counter that is updated every time the bucket is modified, and can be used with the ifRevisionIs parameter to b2_update_bucket to prevent colliding, simultaneous updates.

Example3

options

Array of string

When present and set to s3, the bucket can be accessed through the S3 Compatible API.

Example[ "s3" ]

string

400

status	code	description
400	bad_bucket_id	The requested bucket ID does not match an existing bucket.
400	bad_request	The request had the wrong fields or illegal values. The message returned with the error will describe the problem.

object

status

integer

The numeric HTTP status code. Always matches the status in the HTTP response.

Example400

code

string

A single-identifier code that identifies the error.

Exampleinvalid_bucket_name

message

string

A human-readable message, in English, saying what went wrong.

Examplebucket name is too long

401

status	code	description
401	bad_auth_token	The auth token used is not valid. Call b2_authorize_account again to either get a new one, or an error message describing the problem.
401	expired_auth_token	The auth token used has expired. Call b2_authorize_account again to get a new one.
401	unauthorized	The auth token used is valid, but does not authorize this call with these parameters. The capabilities of an auth token are determined by the application key used with b2_authorize_account.

403

status	code	description
403	transaction_cap_exceeded	Transaction cap exceeded. Daily transaction caps apply to non-paying accounts. To view or adjust your caps, sign in to your B2 Cloud Storage account online and select the Caps & Alerts link in the B2 Cloud Storage section of the sidebar.

Was this article helpful?

What's Next

b2_list_file_names