Object Storage Service:List objects

Flat listing vs. hierarchical listing

Flat listing: all objects under a prefix

Set prefix to the directory path you want to traverse. The response includes all keys that start with that prefix, regardless of how many levels deep they are.

Example bucket contents:

images/cat.jpg
images/dog.png
images/archive/old.zip
readme.txt

With prefix="images/", OSS matches every key that starts with images/ and returns:

images/
images/archive/
images/archive/old.zip
images/cat.jpg
images/dog.png

All objects under images/—including the nested images/archive/old.zip—appear directly in the response.

// ...
ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request(bucketName);
listObjectsV2Request.setPrefix("images/");
ListObjectsV2Result result = ossClient.listObjectsV2(listObjectsV2Request);
// ...

# ...
for page in paginator.iter_page(oss.ListObjectsV2Request(
    bucket='your-bucket',
    prefix='images/',
)):
# ...

// ...
request := &oss.ListObjectsV2Request{
    Bucket: oss.Ptr(bucketName),
    Prefix: oss.Ptr("images/"),
}
// ...

// ...
const result = await client.listV2({ prefix: 'images/' });
// ...

// ...
const res = await client.listObjectsV2({
    bucket: 'yourBucketName',
    prefix: 'images/',
});
// ...

# ...
objects = bucket.list_objects(:prefix => 'images/')
# ...

// ...
ListObjectsRequest request = new ListObjectsRequest("examplebucket");
request.setPrefix("images/");
// ...

// ...
ListObjectsRequest request(BucketName);
request.setPrefix("images/");
// ...

// ...
getBucket.prefix = @"images/";
// ...

// ...
char *prefix = "images/";
aos_str_set(&params->prefix, prefix);
// ...

ossutil api list-objects-v2 --bucket examplebucket --prefix dir/

Hierarchical listing: immediate objects and subdirectories

Add delimiter="/" alongside prefix to split the response into two groups:

• Objects (Contents): keys that do not contain / after the prefix—these are the direct files in the current directory.

• CommonPrefixes: keys that contain / after the prefix are collapsed. The part from the beginning up to the first / is returned as a single entry—these represent subdirectories.

Using the same example bucket:

With prefix="images/" and delimiter="/", OSS processes the filtered results in a second step: keys without a / after the prefix go into Contents; keys with a / are collapsed into CommonPrefixes. The response is:

Objects:
images/
images/cat.jpg
images/dog.png
Directories:
images/archive/

images/archive/old.zip does not appear directly—it is collapsed under images/archive/.

// ...
ListObjectsV2Request listObjectsV2Request = new ListObjectsV2Request(bucketName);
listObjectsV2Request.setPrefix("images/");
listObjectsV2Request.setDelimiter("/");
ListObjectsV2Result result = ossClient.listObjectsV2(listObjectsV2Request);

for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
    System.out.println("Object: " + objectSummary.getKey());
}
for (String commonPrefix : result.getCommonPrefixes()) {
    System.out.println("Subdirectory: " + commonPrefix);
}
// ...

# ...
for page in paginator.iter_page(oss.ListObjectsV2Request(
    bucket=args.bucket,
    prefix="images/",
    delimiter="/",
)):
    for file in page.contents:
        print(f'Object: {file.key}')
    for prefix in page.common_prefixes:
        print(f'Subdirectory: {prefix.prefix}')
# ...

// ...
request := &oss.ListObjectsV2Request{
    Bucket:    oss.Ptr(bucketName),
    Prefix:    oss.Ptr("images/"),
    Delimiter: oss.Ptr("/"),
}
// ...
for _, obj := range lsRes.Contents {
    log.Printf("Object: %v\n", oss.ToString(obj.Key))
}
for _, prefix := range lsRes.CommonPrefixes {
    log.Printf("Subdirectory: %v\n", *prefix.Prefix)
}
// ...

// ...
$paginator = new Oss\Paginator\ListObjectsV2Paginator(client: $client);
$iter = $paginator->iterPage(new Oss\Models\ListObjectsV2Request(
    bucket:    $bucket,
    prefix:    "",
    delimiter: "/"
));

foreach ($iter as $page) {
    foreach ($page->contents ?? [] as $object) {
        echo "Object: " . $object->key . PHP_EOL;
    }
    foreach ($page->commonPrefixes ?? [] as $prefixObject) {
        echo "Subdirectory: " . $prefixObject->prefix . PHP_EOL;
    }
}
// ...

// ...
const result = await client.listV2({
    prefix:    dir,
    delimiter: '/',
});
if (result && result.objects) {
    result.objects.forEach(obj => console.log('Object: %s', obj.name));
}
if (result && result.prefixes) {
    result.prefixes.forEach(subDir => console.log('Subdirectory: %s', subDir));
}
// ...

// ...
const res = await client.listObjectsV2({
    bucket:    'yourBucketName',
    prefix:    'images/',
    delimiter: '/',
});
if (res && res.objects) {
    res.objects.forEach(obj => console.log('Object:', obj.name));
}
if (res && res.prefixes) {
    res.prefixes.forEach(subDir => console.log('Subdirectory:', subDir));
}
// ...

// ...
let result = await client.list({
    prefix:    'images/',
    delimiter: "/",
});
result.objects.forEach(obj  => console.log("Object: %s", obj.name));
result.prefixes.forEach(subDir => console.log("Subdirectory: %s", subDir));
// ...

# ...
objects = bucket.list_objects(prefix: 'images/', delimiter: '/')
objects.each do |obj|
    if obj.is_a?(Aliyun::OSS::Object)
        puts "Object: #{obj.key}"
    elsif obj.is_a?(String)
        puts "Subdirectory: #{obj}"
    end
end
# ...

// ...
ListObjectsRequest request(BucketName);
request.setPrefix("images/");
request.setDelimiter("/");
// ...
for (const auto& object : outcome.result().ObjectSummarys()) {
    std::cout << "Object: " << object.Key() << std::endl;
}
for (const auto& commonPrefix : outcome.result().CommonPrefixes()) {
    std::cout << "Subdirectory: " << commonPrefix << std::endl;
}
// ...

// ...
aos_str_set(&params->prefix,    "images/");
aos_str_set(&params->delimiter, "/");
// ...
aos_list_for_each_entry(oss_list_object_content_t, content,
                        &params->object_list, node) {
    printf("Object: %.*s\n", content->key.len, content->key.data);
}
aos_list_for_each_entry(oss_list_object_common_prefix_t, commonPrefix,
                        &params->common_prefix_list, node) {
    printf("Subdirectory: %.*s\n", commonPrefix->prefix.len, commonPrefix->prefix.data);
}
// ...

ossutil api list-objects-v2 --bucket examplebucket --prefix images/ --delimiter /

Performance optimization

• Maximize page size: Set max-keys to 1,000 to minimize the number of API calls, especially on fast networks. Monitor memory usage when processing each page.

• Process prefixes in parallel: For buckets with hundreds of thousands of objects, sequential listing is slow. Divide the bucket by logical directory (e.g., images/, documents/, logs/) and process each prefix concurrently.

• Cache stable directory structures: If the top-level directory layout rarely changes, cache listing results to avoid redundant API calls.

Cost control

• Avoid periodic full scans: Repeatedly listing all objects in a large bucket generates many API calls. Consider these alternatives:

  • Inventory: generates a complete object manifest on a schedule at lower cost. Best for periodic, large-scale analysis.

  • Event notifications: trigger actions in real time when objects are uploaded or deleted. More efficient than polling with list operations.

• Right-size your page size: A page size that is too small multiplies API calls; one that is too large increases memory consumption and response time per request. Tune maxKeys based on your processing capacity.

Does OSS support listing a specified number of pages of objects?

No. The API does not support page-number-based access. Use continuation tokens (continuationToken / nextContinuationToken) to iterate through pages sequentially.

How do I list all objects in a specific directory?

Set the prefix parameter to the directory path (e.g., images/). To list everything recursively—including nested subdirectories—omit delimiter. To list only the immediate contents, add delimiter="/".

For a command-line option, use list-objects-v2 (get-bucket-v2) in ossutil 2.0.

Is sorting by last modified time supported when listing objects?

No. To find objects by last modified time, use data indexing to query by time range.