ListObjects
Updated at：2025-11-03
API description
This API retrieves the list of object information in a specified bucket.
Request
-
Request syntax
Plain Text1 GET / HTTP/1.1 2 Host: <BucketName>.bj.bcebos.com 3 Date: <Date> 4 Authorization: <AuthorizationString> -
Request headers
No special header parameters
-
Request parameters
| Field | Types | Whether required | Description |
|---|---|---|---|
| delimiter | String | No | The delimiter is primarily used to implement folder listing logic. When specified in a request, BOS truncates matching object names according to certain rules (from the prefix to the first delimiter), deduplicates the truncated strings, and returns them as CommonPrefixes data. The delimiter length is limited to one character. |
| marker | String | No | Objects are listed in alphabetical order, and returned from the first one after the marker |
| maxKeys | Int | No | The maximum length of the returned object list is 1,000, defaulting to 1,000. If the specified value is greater than 1,000, it will be treated as 1,000 |
| prefix | String | No | Key prefix, which must be included in the returned object keys with limits |
Response
| Name | Types | Description |
|---|---|---|
| commonPrefixes | Array | This item is returned only when a delimiter is specified |
| +prefix | String | The matched objects from prefix to the first Delimiter character are returned as a group of elements |
| contents | Array | A list of objects returned |
| +key | String | Object name |
| +lastModified | Date | Last modification time of the object |
| +eTag | String | The HTTP protocol entity tag of object |
| +size | Int | The size of the object content (in bytes) |
| +storageClass | String | Object storage class: return STANDARD_IA for infrequent access storage, COLD for cold storage, ARCHIVE for archive storage, and STANDARD for standard storage. |
| +owner | Container | User information of object uploader |
| ++id | String | User ID of object uploader |
| ++displayName | String | Name of object uploader |
| delimiter | String | Query terminator |
| isTruncated | Bool | Indicate whether the query is fully returned; false - all results are returned this time; true - not all results are returned this time |
| maxKeys | Int | Maximum number of requests returned |
| marker | String | Starting point of this query |
| name | String | Bucket name |
| nextMarker | String | This item is returned only when IsTruncated is true, serving as the marker value for nex query |
| prefix | String | Query prefix |
Plain Text
1> **Note**
2>
3> Delimiter can be used to implement folder logic:
4>
5> 1. If the prefix is set to a folder name, all files starting with that prefix are listed, including all files and subfolders recursively within the folder.
6> 2. If the delimiter is set to "/", the response lists only the files in the folder. Subfolder names are returned in CommonPrefixes, but files within these subfolders are not displayed. For example, if a bucket contains three objects—fun/test.jpg, fun/movie/001.avi, and fun/movie/007.avi—and the prefix is set to "fun/", all three objects will be returned. If the delimiter "/" is also specified, only the file "fun/test.jpg" and the prefix "fun/movie/" will be returned.Example
-
Request example (JSON) 1
JSON1GET / HTTP/1.1 2Host: <BucketName>.bj.bcebos.com 3Date: Wed, 06 Apr 2016 06:34:40 GMT 4Authorization: <AuthorizationString> -
Response example (JSON) 1, recursively listing all objects
JSON1HTTP/1.1 200 OK 2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409 3Date: Wed, 06 Apr 2016 06:34:40 GMT 4Server: BceBos 5{ 6 "name":"bucket", 7 "prefix":"", 8 "delimiter":"/", 9 "marker":"", 10 "maxKeys":1000, 11 "isTruncated":false, 12 "contents":[ 13 { 14 "key":"my-image.jpg", 15 "lastModified":"2009-10-12T17:50:30Z", 16 "eTag":"fba9dede5f27731c9771645a39863328", 17 "size":434234, 18 "storageClass":"STANDARD", 19 "owner":{ 20 "id":"168bf6fd8fa74d9789f35a283a1f15e2", 21 "displayName":"mtd" 22 } 23 }, 24 { 25 "key":"my-image1.jpg", 26 "lastModified":"2009-10-12T17:51:30Z", 27 "eTag":"0cce7caecc8309864f663d78d1293f98", 28 "size":124231, 29 "storageClass":"COLD", 30 "owner":{ 31 "id":"168bf6fd8fa74d9789f35a283a1f15e2", 32 "displayName":"mtd" 33 } 34 ] 35} -
Request example (JSON) 2, listing partial files in the root directory and subdirectories, limited by maxKeys (excluding files in the subdirectories)
JSON1GET /?delimiter=/ HTTP/1.1 2Host: <BucketName>.bj.bcebos.com 3Date: Wed, 06 Apr 2016 06:34:40 GMT 4Authorization: <AuthorizationString> -
Response example (JSON) 2
JSON1HTTP/1.1 200 OK 2x-bce-request-id: 4db2b34d-654d-4d8a-b49b-3049ca786409 3Date: Wed, 06 Apr 2016 06:34:40 GMT 4Server: BceBos 5{ 6 "name":"bucket", 7 "prefix":"" , 8 "delimiter":"/", 9 "marker":"", 10 "maxKeys":1000, 11 "isTruncated":false, 12 "contents":[ 13 { 14 "key":"my-image.jpg", 15 "lastModified":"2009-10-12T17:50:30Z", 16 "eTag":"fba9dede5f27731c9771645a39863328", 17 "size":434234, 18 "storageClass":"STANDARD", 19 "owner":{ 20 "id":"168bf6fd8fa74d9789f35a283a1f15e2", 21 "displayName":"mtd" 22 } 23 } 24 ], 25 "commonPrefixes":[ 26 {"prefix":"photos/"}, 27 {"prefix":"mtd/"} 28 ] 29}