View the object in the bucket

Updated at：2025-11-03

View the object in the bucket.

Simple query

View the list of objects in a bucket.

Basic workflow
1. Create a BosClient instance.
2. Run the listObjects() method.

Example code

                JavaScript
                
            

                client.listObjects(<bucketName>)
  .then(function (response) {
      var contents = response.body.contents;
      for (var i = 0, l = contents.length; i < l; i++) {
          console.log(contents[i].key);
      }
  })
  .catch(function (error) {
 // Query failed
  });
            

Plain Text

1> **Note:**
2>
3> -   By default, if the number of objects in the bucket exceeds 1,000, only 1,000 objects will be returned. In this case, the IsTruncated value in the returned result will be set to True, and NextMarker will be provided as the starting point for the next retrieval.
4>
5> -   To retrieve more objects, use the Marker parameter for reading in batches. Refer to [Extended Query](#Extended query).

Extended query

Users can configure listObjects parameters to activate additional extended query features. The configurable extended parameters are as follows:

Parameter name	Description	Default value
maxKeys	Specify the maximum number of objects to return, which must not exceed 1,000.	1000
prefix	Set the prefix of the objectKey. The prefix means that the objectKey contains and starts with the value of prefix. It is usually used in conjunction with delimiter when [querying simulated folders](#Query simulated folders).	-
delimiter	It is a delimiter used to hierarchize objectKey. It is usually used in conjunction with prefix when [querying simulated folders](#Query simulated folders). The objectKey from the prefix to the first occurrence of the delimiter character is called: commonPrefixes.	-
marker	It is a string used to set the starting position of the returned results. After setting the marker value, the returned objects will be returned starting from the marker value in alphabetical order.	-

Example code

                JavaScript
                
            

                // Set parameters
var options = {
    delimiter: '/',
    marker: '123'
};
client.listObjects(<bucketName>, options)
    .then(function (response) {
        var contents = response.body.contents;
        for (var i = 0, l = contents.length; i < l; i++) {
            console.log(contents[i].key);
        }
    })
    .catch(function (error) {
 // Query failed
    });
            

Query simulated folders

Since BOS is inherently a (<Key>,<Value>) storage system, the concept of "folder" does not exist in principle. However, you can simulate the folder function by combining the delimiter and prefix parameters.

Suppose the bucket contains five files: bos.jpg, fun/, fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi. The "/" symbol can be used as a delimiter to mimic folder structures.

Recursively list all files under the simulated folder

You can obtain all files under a simulated folder by setting the Prefix parameter:

                JavaScript
                
            

                // Set parameters
let options = {
 prefix: 'fun/' // Recursively list all files under the fun directory
};
client.listObjects(<bucketName>, options)
.then(function (response) {
    console.log('Objects:');
    var contents = response.body.contents;
    for (var i = 0, l = contents.length; i < l; i++) {
        console.log(contents[i].key);
    }
})
.catch(function (error) {
 // Query failed
});
            

Output:

                JavaScript
                
            

                Objects:
fun/
fun/movie/001.avi
fun/movie/007.avi
fun/test.jpg
            

View files and subfolders under the simulated folder

With the combination of Prefix and Delimiter, it can list files and subfolders under the simulated folder:

                JavaScript
                
            

                // Set parameters
let options = {
 prefix: 'fun/',//List all files and folders under the “fun” directory
 delimiter: '/' // "/" is the delimiter for folders
};
client.listObjects(<bucketName>, options)
.then(function (response) {
    console.log('Objects:');
    var contents = response.body.contents;
    for (var i = 0, l = contents.length; i < l; i++) {
        console.log(contents[i].key);
    }
    console.log('CommonPrefixs:');
    var commonPrefixes = response.body.commonPrefixes;
    for (i = 0, l = commonPrefixes.length; i < l; i++) {
        console.log(commonPrefixes[i]);
    }
})
.catch(function (error) {
 // Query failed
});
            

Output:

                JavaScript
                
            

                Objects:
fun/
fun/test.jpg
CommonPrefixs:
fun/movie/
            

Note: In the returned results, the list of objects shows the files under the “fun” folder. The list in CommonPrefixs shows all subfolders under the fun folder. It can be seen that the two files fun/movie/001.avi and fun/movie/007.avi are not listed because they belong to the movie subfolder under the fun folder.

Get Object

Copy Object