b2_list_file_names

NOTE:

This API request is now being described as a GET request and not a POST request, as was the case in previous versions of our documentation.

We made this update because we believe that an API call that retrieves data and does not alter state is more accurately represented as a GET request.

You may still make a POST request to this endpoint by simply submitting a JSON-formatted request body containing the parameters, with Content-Type set to application/json.

Lists the names of all files in a bucket, starting at a given name

This call returns at most 10,000 file names per transaction, but it can be called repeatedly to scan through all of the file names in a bucket. Each time you call, it returns a "nextFileName" that can be used as the starting point for the next call.

Please note: billing is per 1000 files/versions returned. For example, if 10,000 file names are requested and returned, you will be billed for 10 API calls.

There may be many file versions for the same name, but this call will return each name only once. Files that have been hidden will not be returned; to see all versions of a file, including hide markers, use b2_list_file_versions instead.

To go through all of the file names in a bucket, use a loop like this:

startFileName = null   
while true:
    response = b2_list_file_names(bucketId = ..., startFileName = startFileName)
    for file in response.files:
        process_one_file_name(file)
    if response.startFileName == null:
        break
    startFileName = response.nextFileName

Prefixes and Delimiters

You can optionally specify a file name prefix, which will restrict the results to only files starting with that prefix.

Another option is to specify a delimiter (usually "/") for folder names. If found after the file name prefix, the delimiter is treated as the end of a folder name, and the folder name is returned, replacing all of the files in that folder. Each item returned is either an "upload" (a file) or a "folder" (representing one or many files).

As an example, if you have these files in your bucket:

photos/alice.jpg 

photos/alfred.jpg 

photos/cats/fluffy.jpg 

photos/cats/mittens.jpg 

photos/dogs/spot.jpg 

photos/lilly.jpg

With the default prefix of "" and no delimiter, you get all of the files:

upload    photos/alice.jpg 

upload    photos/alfred.jpg 

upload    photos/cats/fluffy.jpg 

upload    photos/cats/mittens.jpg 

upload    photos/dogs/spot.jpg 

upload    photos/lilly.jpg

If you use a prefix of "photos/c" you will get the same list as if you specify "photos/cats/" as the prefix:

upload    photos/cats/fluffy.jpg

upload    photos/cats/mittens.jpg

With a prefix of "" (meaning all files), and a delimiter of "/", you would get:

folder photos/

With a prefix of "photos/", and a delimiter of "/", you would get:

upload    photos/alice.jpg

upload    photos/alfred.jpg

folder    photos/cats/

folder    photos/dogs/

upload    photos/lilly.jpg

Prefixes are parsed as literal strings, so regular expressions and wildcards cannot be used in this context. For example, a prefix of .*cats would only find a match if a file's full name starts with the literal string .*cats.

Bucket and Prefix Restrictions

When using an application key that is restricted to one bucket, and to files matching a name prefix in that bucket, you must only ask about those files. Listing files in other buckets is not allowed. Listing files that do not match the prefix is not allowed, so you must specify a prefix that is at least as restrictive as the one in the application key.

API Versions

v2: Object Lock (May 11, 2021)

Now returns fileRetention and legalHold.

v2: Server-Side Encryption (March 5, 2021)

Now returns serverSideEncryption.

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

Listing file names will always return all of the file names you ask for. If your application key has a file name prefix restriction, and you ask for files outside that prefix, the call is unauthorized.

Now returns accountId and bucketId. Does not return size any more; use contentLength instead.

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

When using an application key with a file name prefix restriction, a request to list files will be filtered to show only files allowed by the application key.

v1: Original release (September 22, 2015)

Original release.

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