Amplify has re-imagined the way frontend developers build fullstack applications. Develop and deploy without the hassle.

Fullstack TypeScript

Write your app's data model, auth, storage, and functions in TypeScript; Amplify will do the rest.

Built with the AWS CDK

Use any cloud resource your app needs. Never worry about scale.

Learn more

Choose your framework/language

v1v2
Edit on GitHub

Page updated May 2, 2024

List files

The latest version of Amplify Storage supports specifying S3 objects as a paths.
We recommend using path instead of key to specify S3 objects.

Note: key parameter is deprecated and may be removed in next major version.

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.

With StoragePath

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

let listResult = try await Amplify.Storage.list(
    path: .fromString("public/photos/")
)
listResult.items.forEach { item in
    print("Path: \(item.path)")
}
let sink = Amplify.Publisher.create {
    try await Amplify.Storage.list(
        path: .fromString("public/photos/") 
    )
}.sink {
    if case let .failure(error) = $0 {
        print("Failed: \(error)")
    }
}
receiveValue: { listResult in
    listResult.items.forEach { item in
        print("Path: \(item.path)")
    }
}

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.

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 .exclude:

let listResult = try await Amplify.Storage.list(
    path: .fromString("public/photos/"),
    options: .init(
        subpathStrategy: .exclude
    )
)
listResult.items.forEach { item in
    print("Path: \(item.path)")
}
listResult.excludedSubpaths.forEach { subpath in
    print("Subpath: \(subpath)")
}
let sink = Amplify.Publisher.create {
    try await Amplify.Storage.list(
        path: .fromString("public/photos/"),
        options: .init(
            subpathStrategy: .exclude
        )
    )
}.sink {
    if case let .failure(error) = $0 {
        print("Failed: \(error)")
    }
}
receiveValue: { listResult in
    listResult.items.forEach { item in
        print("Path: \(item.path)")
    }
    listResult.excludedSubpaths.forEach { subpath in
        print("Subpath: \(subpath)")
    }
}

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:

let listResult = try await Amplify.Storage.list(
    path: .fromString("public/photos-"),
    options: .init(
        subpathStrategy: .exclude(delimitedBy: "-")
    )
)
let sink = Amplify.Publisher.create {
    try await Amplify.Storage.list(
        path: .fromString("public/photos-"),
        options: .init(
            subpathStrategy: .exclude(delimitedBy: "-")
        )
    )
}.sink {
    if case let .failure(error) = $0 {
        print("Failed: \(error)")
    }
}
receiveValue: { listResult in
    // ...
}

With Key (Deprecated)

The following example lists all public files:

let listResult = try await Amplify.Storage.list()
listResult.items.forEach { item in
    print("Key: \(item.key)")
}
let sink = Amplify.Publisher.create {
    try await Amplify.Storage.list()
}.sink {
    if case let .failure(error) = $0 {
        print("Failed: \(error)")
    }
}
receiveValue: { listResult in
    print("Completed")
    listResult.items.forEach { item in
        print("Key: \(item.key)")
    }
}

You can also list private or protected files by passing options. For example, to list all protected files owned by a user identified by the ID otherUserID (This behavior is deprecated):

let listResult = try await Amplify.Storage.list(
    options: .init(
        accessLevel: .protected, 
        targetIdentityId: "otherUserID"
    )
)
listResult.items.forEach { item in
    print("Key: \(item.key)")
}
let sink = Amplify.Publisher.create {
    let options = StorageListRequest.Options)
    try await Amplify.Storage.list(
        options: .init(
            accessLevel: .protected, 
            targetIdentityId: "otherUserID"
        )
    )
}.sink {
    if case let .failure(error) = $0 {
        print("Failed: \(error)")
    }
}
receiveValue: { listResult in
    listResult.items.forEach { item in
        print("Key: \(item.path)")
    }
}

If you like limit the response to keys that begin with the specified path provide the path options (This behavior is deprecated):

let listResult = try await Amplify.Storage.list(
    options: .init(
        path: "path"
    )
)
listResult.items.forEach { item in
    print("Key: \(item.key)")
}
let sink = Amplify.Publisher.create {
    try await Amplify.Storage.list(
        options: .init(
            path: "path"
        )
    )
}.sink {
    if case let .failure(error) = $0 {
        print("Failed: \(error)")
    }
}
receiveValue: { listResult in
    listResult.items.forEach { item in
        print("Key: \(item.key)")
    }
}

More list options

OptionTypeDescription
pageSizeUIntNumber between 1 and 1,000 that indicates the limit of how many entries to fetch when retrieving file lists from the server
nextTokenStringString 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.

PREVIOUS
Download files
NEXT
Remove files
Site color mode

Amplify open source software, documentation and community are supported by Amazon Web Services.

© 2024, Amazon Web Services, Inc. and its affiliates.

All rights reserved. View the site terms and privacy policy.

Flutter and the related logo are trademarks of Google LLC. We are not endorsed by or affiliated with Google LLC.