Skip to content

Directory Listing

- (void)listingWithPath:(NSString * _Nonnull)path responseHandler:^(NSArray<BackendlessFileInfo *> * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;

- (void)listingWithPattern:(NSString * _Nonnull)pattern recursive:(BOOL)recursive responseHandler:^(NSArra<BackendlessFileInfo *> * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;

- (void)listingWithPath:(NSString * _Nonnull)path pattern:(NSString * _Nonnull)pattern recursive:(BOOL)recursive responseHandler:^(NSArray<BackendlessFileInfo *> * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;

- (void)listingWithPath:(NSString * _Nonnull)path pattern:(NSString * _Nonnull)pattern recursive:(BOOL)recursive pageSize:(NSInteger)NSPageSize offset:(NSInteger)offset responseHandler:^(NSArray<BackendlessFileInfo *> * _Nonnull)responseHandler errorHandler:^(Fault * _Nonnull)errorHandler;
func listing(path: String, responseHandler: (([BackendlessFileInfo]) -> Void)!, errorHandler: ((Fault) -> Void)!)

func listing(pattern: String, recursive: Bool, responseHandler: (([BackendlessFileInfo]) -> Void)!, errorHandler: ((Fault) -> Void)!)

func listing(path: String, pattern: String, recursive: Bool, responseHandler: (([BackendlessFileInfo]) -> Void)!, errorHandler: ((Fault) -> Void)!)

func listing(path: String, pattern: String, recursive: Bool, pageSize: Int, offset: Int, responseHandler: (([BackendlessFileInfo]) -> Void)!, errorHandler: ((Fault) -> Void)!)


Argument                Description
path path of a directory to get a listing of. The path must start with the root directory identified by forward slash, for example: "/web".
pattern a pattern which the returned files and directories must match. The pattern can include wildcard characters. Asterisk (*) matches a substring of any length. Question mark (?) matches only one character in the file/directory name.
recursive an optional parameter. If present and is true, requests that the listing must be retrieved recursively for all directories contained within .
pageSize an optional parameter. If present, identifies how many items should be returned in the response.
offset an optional parameter. If present, indicates the index of item in the response from which to get the <pagesize> items.

Return Value

Methods return an array of the FileInfo objects. The object provides information about file name, when the file was created, its public URL and the internal url:

@interface FileInfo : NSObject

@property (strong, nonatomic) NSString *name;
@property (strong, nonatomic) NSNumber *createdOn;
@property (strong, nonatomic) NSString *publicUrl;
@property (strong, nonatomic) NSNumber *size;
@property (strong, nonatomic) NSString *url;

@objcMembers open class FileInfo: NSObject {     
    open var name: String?
    open var createdOn: NSNumber?
    open var publicUrl: String?
    open var size: NSNumber = 0
    open var url: String?    

Return value

A collection of files and directories matching the specified pattern. The returned collection may not include all files and directories as the size of the number of returned entries is limited for paging purposes. To get the next set of file/directory entries, an additional request must be made with a different offset value. The total count of all files/directories in the listing use the Get File Count API.

Each element in the collection contains the following properties:

  • name - name of the file or directory without any path information
  • public URL - absolute URL of the file or directory
  • URL - relative URL of the file or directory starting from the root of the file storage
  • created on - a timestamp indicating when the file or directory were created


The example below describes how to get a listing of all HTML files from the /web directory and all subdirectories.

[Backendless.shared.file listingWithPath:@"web" pattern:@"*.html" recursive:YES responseHandler:^(NSArray *files) {
    for (BackendlessFileInfo *file in files) {
        NSLog(@"%@ [%@]",, file.url);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
Backendless.shared.file.listing(path: "web", pattern: "*.html", recursive: true, responseHandler: { files in
    for file in files {
        print("\( ?? "") [\(file.url ?? "")]")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")


The server may return the following errors:

Error Code
Error message
File or directory cannot be found.
Occurs when the source file/directory cannot be found.
Path contains prohibited symbols: {path name}

The specified resource was not found
Occurs when the API requests to rename a non-existent file or a directory.
Specified resource must be a directory
Occurs when the path to get a listing for is not a directory