Skip to navigation
Dropbox APIUser EndpointsFiles

List Folder

View as Markdown

Starts returning the contents of a folder. If the result’s ListFolderResult.has_more field is true, call list_folder/continue with the returned ListFolderResult.cursor to retrieve more entries. If you’re using ListFolderArg.recursive set to true to keep a local cache of the contents of a Dropbox account, iterate through each entry in order and process them as follows to keep your local state in sync: For each FileMetadata, store the new entry at the given path in your local state. If the required parent folders don’t exist yet, create them. If there’s already something else at the given path, replace it and remove all its children. For each FolderMetadata, store the new entry at the given path in your local state. If the required parent folders don’t exist yet, create them. If there’s already something else at the given path, replace it but leave the children as they are. Check the new entry’s FolderSharingInfo.read_only and set all its children’s read-only statuses to match. For each DeletedMetadata, if your local state has something at the given path, remove it and all its children. If there’s nothing at the given path, ignore this entry. Note: auth.RateLimitError may be returned if multiple list_folder or list_folder/continue calls with same parameters are made simultaneously by same API app for same user. If your app implements retry logic, please hold off the retry until the previous request finishes.

Required scope: files.metadata.read

Endpoint format: RPC

Authentication: App, User, Dropbox-API-Select-Admin (Whole Team)

Authentication

AuthorizationBearer

App-level OAuth 2.0 token (no user context). Use Authorization: Bearer <token>.

Obtain by calling the token endpoint with grant_type=client_credentials.

Only available on endpoints that declare app auth support.

OR
AuthorizationBearer

OAuth 2.0 token issued to a specific user. Use Authorization: Bearer <token>.

Public clients should use the authorization code flow with PKCE (S256).

For background or offline access, send token_access_type=offline during authorization and use the returned refresh token to obtain new access tokens.

You can generate a short-lived access token from the App Console; see Testing with a generated token.

Headers

Dropbox-API-Select-UserstringOptional

Acts on behalf of a team member for supported user-auth operations. Pass a team member ID such as dbmid:.... When used with a team token, that token must also include the team_data.member scope.

Dropbox-API-Select-AdminstringOptional

Acts as the specified team admin for supported user-auth operations. Pass a team member ID for an admin account. When used with a team token, that token must also include the team_data.member scope.

Dropbox-API-Path-RootstringOptional

Scopes path-based operations to a namespace (root). The value is a JSON serialization of the common.PathRoot union: {".tag": "home"}, {".tag": "root", "root": "<namespace_id>"}, or {".tag": "namespace_id", "namespace_id": "<namespace_id>"}. On failure the request returns 422 with a common.PathRootError.

Request

This endpoint expects an object.
pathstringRequiredformat: "(/(.|[\r\n])*)?|id:.*|(ns:[0-9]+(/(.|[\r\n])*)?)"
A unique identifier for the file.
include_deletedbooleanOptionalDefaults to false
If true, the results will include entries for files and folders that used to exist but were deleted.
include_has_explicit_shared_membersbooleanOptionalDefaults to false
If true, the results will include a flag for each file indicating whether or not that file has any explicit members.
include_mounted_foldersbooleanOptionalDefaults to true
If true, the results will include entries under mounted folders which includes app folder, shared folder and team folder.
include_non_downloadable_filesbooleanOptionalDefaults to true
If true, include files that are not downloadable, i.e. Google Docs.
include_property_groupsobject or nullOptional

If set to a valid list of template IDs, FileMetadata.property_groups is set if there exists property data associated with the file and each of the listed templates.

Variant:
file_properties.TemplateFilterBase.filter_someobjectRequired

Only templates with an ID in the supplied list will be returned (a subset of templates will be returned).

include_restorable_infobooleanOptionalDefaults to false
If true, each returned deleted entry will include whether that entry can be restored.
limituint or nullOptional1-2000

The maximum number of results to return per request. Note: This is an approximate number and there can be slightly more entries returned in some cases.

recursivebooleanOptionalDefaults to false

If true, the list folder operation will be applied recursively to all subfolders and the response will contain contents of all subfolders. In some cases, setting ListFolderArg.recursive to true may lead to performance issues or errors, especially when traversing folder structures with a large number of items. A workaround for such cases is to set ListFolderArg.recursive to false and traverse subfolders one at a time.

include_media_infobooleanOptionalDefaults to falseDeprecated

If true, FileMetadata.media_info is set for photo and video. This parameter will no longer have an effect starting December 2, 2019.

Response headers

X-Dropbox-Request-IdstringOptional
A unique identifier for the request, useful for debugging and support.

Response

Successful response
cursorstring>=1 character

Pass the cursor into list_folder/continue to see what’s changed in the folder since your previous query.

entrieslist of objects

The files and (direct) subfolders in the folder.

Variant:
files.Metadata.fileobject
has_moreboolean

If true, then there are more entries available. Pass the cursor to list_folder/continue to retrieve the rest.

Errors

401
Unauthorized Error
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error