List file properties

You can list files without having to download all the files. You can do this by using the list API from the Amplify Library for Storage.

List Files

The following example lists all objects inside the public/photos/ path:

StoragePagedListOptions options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .build();
Amplify.Storage.list(
    StoragePath.fromString("public/photos/"),
    options,
    result -> {
        for (StorageItem item : result.getItems()) {
            Log.i("MyAmplifyApp", "Item: " + item.getPath());
        Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
    error -> Log.e("MyAmplifyApp", "List failure", error);

val options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .build()
Amplify.Storage.list(StoragePath.fromString("public/photos/"), options,
    { result ->
        result.items.forEach { item ->
            Log.i("MyAmplifyApp", "Item: ${item.path}")
        Log.i("MyAmplifyApp", "Next Token: ${result.nextToken}")
    { Log.e("MyAmplifyApp", "List failure", it) }

val options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .build()
    val result = Amplify.Storage.list(StoragePath.fromString("public/photos/"), options)
    result.items.forEach {
        Log.i("MyAmplifyApp", "Item: $it")
    Log.i("MyAmplifyApp", "next token: ${result.nextToken}")
} catch (error: StorageException) {
    Log.e("MyAmplifyApp", "List failure", error)

StoragePagedListOptions options = StoragePagedListOptions.builder()
        .setPageSize(1000)
        .build();
RxAmplify.Storage.list(StoragePath.fromString("public/photos/"), options)
        .subscribe(
            result -> {
                for (StorageItem item : result.getItems()) {
                    Log.i("MyAmplifyApp", "Item: " + item.getPath());
                Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
            error -> Log.e("MyAmplifyApp", "List failure", error);

Note the trailing slash / in the given path.

If you had used public/photos as path, it would also match against files like public/photos01.jpg.

List files from a specified bucket

You can also perform a list operation to a specific bucket by providing the bucket option. You can pass in a string representing the target bucket's assigned name in Amplify Backend.

StorageBucket secondBucket = StorageBucket.fromOutputs("secondBucket");
StoragePagedListOptions options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .bucket(secondBucket)
    .build();
Amplify.Storage.list(
    StoragePath.fromString("public/photos/"),
    options,
    result -> {
        for (StorageItem item : result.getItems()) {
            Log.i("MyAmplifyApp", "Item: " + item.getPath());
        Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
    error -> Log.e("MyAmplifyApp", "List failure", error);

val secondBucket = StorageBucket.fromOutputs("secondBucket")
val options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .bucket(secondBucket)
    .build()
Amplify.Storage.list(StoragePath.fromString("public/photos/"), options,
    { result ->
        result.items.forEach { item ->
            Log.i("MyAmplifyApp", "Item: ${item.path}")
        Log.i("MyAmplifyApp", "Next Token: ${result.nextToken}")
    { Log.e("MyAmplifyApp", "List failure", it) }

val secondBucket = StorageBucket.fromOutputs("secondBucket")
val options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .bucket(secondBucket)
    .build()
    val result = Amplify.Storage.list(StoragePath.fromString("public/photos/"), options)
    result.items.forEach {
        Log.i("MyAmplifyApp", "Item: $it")
    Log.i("MyAmplifyApp", "next token: ${result.nextToken}")
} catch (error: StorageException) {
    Log.e("MyAmplifyApp", "List failure", error)

StorageBucket secondBucket = StorageBucket.fromOutputs("secondBucket");
StoragePagedListOptions options = StoragePagedListOptions.builder()
        .setPageSize(1000)
        .bucket(secondBucket)
        .build();
RxAmplify.Storage.list(StoragePath.fromString("public/photos/"), options)
        .subscribe(
            result -> {
                for (StorageItem item : result.getItems()) {
                    Log.i("MyAmplifyApp", "Item: " + item.getPath());
                Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
            error -> Log.e("MyAmplifyApp", "List failure", error);

Alternatively, you can also pass in an object by specifying the bucket name and region from the console.

BucketInfo bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2");
StorageBucket secondBucket = StorageBucket.fromBucketInfo(bucketInfo);
StoragePagedListOptions options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .bucket(secondBucket)
    .build();
Amplify.Storage.list(
    StoragePath.fromString("public/photos/"),
    options,
    result -> {
        for (StorageItem item : result.getItems()) {
            Log.i("MyAmplifyApp", "Item: " + item.getPath());
        Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
    error -> Log.e("MyAmplifyApp", "List failure", error);

val bucketInfo = BucketInfo("second-bucket-name-from-console", "us-east-2")
val secondBucket = StorageBucket.fromBucketInfo(bucketInfo)
val options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .bucket(secondBucket)
    .build()
Amplify.Storage.list(StoragePath.fromString("public/photos/"), options,
    { result ->
        result.items.forEach { item ->
            Log.i("MyAmplifyApp", "Item: ${item.path}")
        Log.i("MyAmplifyApp", "Next Token: ${result.nextToken}")
    { Log.e("MyAmplifyApp", "List failure", it) }

val bucketInfo = BucketInfo("second-bucket-name-from-console", "us-east-2")
val secondBucket = StorageBucket.fromBucketInfo(bucketInfo)
val options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .bucket(secondBucket)
    .build()
    val result = Amplify.Storage.list(StoragePath.fromString("public/photos/"), options)
    result.items.forEach {
        Log.i("MyAmplifyApp", "Item: $it")
    Log.i("MyAmplifyApp", "next token: ${result.nextToken}")
} catch (error: StorageException) {
    Log.e("MyAmplifyApp", "List failure", error)

BucketInfo bucketInfo = new BucketInfo("second-bucket-name-from-console", "us-east-2");
StorageBucket secondBucket = StorageBucket.fromBucketInfo(bucketInfo);
StoragePagedListOptions options = StoragePagedListOptions.builder()
        .setPageSize(1000)
        .bucket(secondBucket)
        .build();
RxAmplify.Storage.list(StoragePath.fromString("public/photos/"), options)
        .subscribe(
            result -> {
                for (StorageItem item : result.getItems()) {
                    Log.i("MyAmplifyApp", "Item: " + item.getPath());
                Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
            error -> Log.e("MyAmplifyApp", "List failure", error);

Exclude results from nested subpaths

By default, the list API will return all objects contained within the given path, including objects inside nested subpaths.

For example, the previous public/photos/ path would include these objects:

Path: public/photos/photo1.jpg
Path: public/photos/vacation/photo1.jpg
Path: public/photos/thumbnails/photo1.jpg

In order to exclude objects within the vacation and thumbnails subpaths, you can set the subpathStrategy option to SubpathStrategy.Exclude():

StoragePagedListOptions options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .setSubpathStrategy(SubpathStrategy.Exclude())
    .build();
Amplify.Storage.list(
    StoragePath.fromString("public/photos/"),
    options,
    result -> {
        for (StorageItem item : result.getItems()) {
            Log.i("MyAmplifyApp", "Item: " + item.getPath());
        Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
    error -> Log.e("MyAmplifyApp", "List failure", error);

val options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .setSubpathStrategy(SubpathStrategy.Exclude())
    .build()
Amplify.Storage.list(StoragePath.fromString("public/photos/"), options,
    { result ->
        result.items.forEach { item ->
            Log.i("MyAmplifyApp", "Item: ${item.path}")
        Log.i("MyAmplifyApp", "Next Token: ${result.nextToken}")
    { Log.e("MyAmplifyApp", "List failure", it) }

val options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .setSubpathStrategy(SubpathStrategy.Exclude())
    .build()
    val result = Amplify.Storage.list(StoragePath.fromString("public/photos/"), options)
    result.items.forEach {
        Log.i("MyAmplifyApp", "Item: $it")
    Log.i("MyAmplifyApp", "next token: ${result.nextToken}")
} catch (error: StorageException) {
    Log.e("MyAmplifyApp", "List failure", error)

StoragePagedListOptions options = StoragePagedListOptions.builder()
        .setPageSize(1000)
        .setSubpathStrategy(SubpathStrategy.Exclude())
        .build();
RxAmplify.Storage.list(StoragePath.fromString("public/photos/"), options)
        .subscribe(
            result -> {
                for (StorageItem item : result.getItems()) {
                    Log.i("MyAmplifyApp", "Item: " + item.getPath());
                Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
            error -> Log.e("MyAmplifyApp", "List failure", error);

The response will only include objects within the public/photos/ path and will also provide a list of the excluded subpaths:

Path: public/photos/photo01.jpg
Subpath: public/photos/vacation/
Subpath: public/photos/thumbnails/

The default delimiter character is "/", but this can be changed by supplying a custom delimiter:

StoragePagedListOptions options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .setSubpathStrategy(SubpathStrategy.Exclude("-"))
    .build();
Amplify.Storage.list(
    StoragePath.fromString("public/photos/"),
    options,
    result -> {
        for (StorageItem item : result.getItems()) {
            Log.i("MyAmplifyApp", "Item: " + item.getPath());
        Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
    error -> Log.e("MyAmplifyApp", "List failure", error);

val options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .setSubpathStrategy(SubpathStrategy.Exclude("-"))
    .build()
Amplify.Storage.list(StoragePath.fromString("public/photos/"), options,
    { result ->
        result.items.forEach { item ->
            Log.i("MyAmplifyApp", "Item: ${item.path}")
        Log.i("MyAmplifyApp", "Next Token: ${result.nextToken}")
    { Log.e("MyAmplifyApp", "List failure", it) }

val options = StoragePagedListOptions.builder()
    .setPageSize(1000)
    .setSubpathStrategy(SubpathStrategy.Exclude("-"))
    .build()
    val result = Amplify.Storage.list(StoragePath.fromString("public/photos/"), options)
    result.items.forEach {
        Log.i("MyAmplifyApp", "Item: $it")
    Log.i("MyAmplifyApp", "next token: ${result.nextToken}")
} catch (error: StorageException) {
    Log.e("MyAmplifyApp", "List failure", error)

StoragePagedListOptions options = StoragePagedListOptions.builder()
        .setPageSize(1000)
        .setSubpathStrategy(SubpathStrategy.Exclude("-"))
        .build();
RxAmplify.Storage.list(StoragePath.fromString("public/photos/"), options)
        .subscribe(
            result -> {
                for (StorageItem item : result.getItems()) {
                    Log.i("MyAmplifyApp", "Item: " + item.getPath());
                Log.i("MyAmplifyApp", "Next Token: " + result.getNextToken());
            error -> Log.e("MyAmplifyApp", "List failure", error);

The response will only include objects within the public/photos/ path not grouped by the delimiter -.

Path: public/photos/2023/photos01.jpg
Path: public/photos/2024/photos02.jpg
Subpath: public/photos/202-

All `list` options

Option	Type	Description
subpathStrategy	SubpathStrategy	The strategy to use when listing contents from subpaths.
pageSize	int	Number between 1 and 1,000 that indicates the limit of how many entries to fetch when retrieving file lists from the server.
bucket	StorageBucket	The bucket in which the objects are stored.
nextToken	String	String indicating the page offset at which to resume a listing.

If the pageSize is set lower than the total file size available, a single list call only returns a subset of all the files. To list all the files with multiple calls, the user can use the nextToken value from the previous response.

Download files

Remove files

List file properties

List Files

List files from a specified bucket

Exclude results from nested subpaths

All list options

All `list` options