Back to DropboxFiles - List Folder
Starts returning the contents of a folder. If the result's :field:ListFolderResult.has_more
field is :val:true
, call :route:list_folder/continue
with the returned :field:ListFolderResult.cursor
to retrieve more entries.
If you're using :field:ListFolderArg.recursive
set to :val: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 :type: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 :type: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 :field:FolderSharingInfo.read_only
and set all its children's read-only statuses to match.
For each :type: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: :type:auth.RateLimitError
may be returned if multiple :route:list_folder
or :route: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.
Input
type: object
properties:
data:
type: object
description: >
path: A unique identifier for the file.
recursive: If true, the list folder operation will be applied recursively
to all subfolders and the response will contain contents of all
subfolders.
include_media_info: If true, :field:`FileMetadata.media_info` is set for
photo and video.
include_deleted: If true, the results will include entries for files and
folders that used to exist but were deleted.
include_has_explicit_shared_members: If true, the results will include a
flag for each file indicating whether or not that file has any explicit
members.
include_mounted_folders: If true, the results will include entries under
mounted folders which includes app folder, shared folder and team folder.
limit: 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.
shared_link: A shared link to list the contents of. If the link is
password-protected, the password must be provided. If this field is
present, :field:`ListFolderArg.path` will be relative to root of the
shared link. Only non-recursive mode is supported for shared link.
include_property_groups: If set to a valid list of template IDs,
:field:`FileMetadata.property_groups` is set if there exists property data
associated with the file and each of the listed templates.
properties:
shared_link:
type: object
description: |
url: Shared link url.
password: Password for the shared link.
properties:
url:
type: string
description: Shared link url.
password:
type: string
description: Password for the shared link.
include_property_groups:
type: object
description: >
filter_some: Only templates with an ID in the supplied list will be
returned (a subset of templates will be returned).
other: None
properties:
filter_some:
type: array
description: >-
Only templates with an ID in the supplied list will be returned (a
subset of templates will be returned).
items:
type: string
.tag:
title: Choice of TemplateFilterBase
type: string
enum:
- filter_some
- other
recursive:
type: boolean
description: >-
If true, the list folder operation will be applied recursively to all
subfolders and the response will contain contents of all subfolders.
include_has_explicit_shared_members:
type: boolean
description: >-
If true, the results will include a flag for each file indicating
whether or not that file has any explicit members.
include_deleted:
type: boolean
description: >-
If true, the results will include entries for files and folders that
used to exist but were deleted.
limit:
type: number
description: >-
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.
include_media_info:
type: boolean
description: If true, :field:`FileMetadata.media_info` is set for photo and video.
include_mounted_folders:
type: boolean
description: >-
If true, the results will include entries under mounted folders which
includes app folder, shared folder and team folder.
path:
type: string
description: A unique identifier for the file.
title: Data
Output
type: object
description: >
entries: The files and (direct) subfolders in the folder.
cursor: Pass the cursor into :route:`list_folder/continue` to see what's
changed in the folder since your previous query.
has_more: If true, then there are more entries available. Pass the cursor to
:route:`list_folder/continue` to retrieve the rest.
properties:
cursor:
type: string
description: >-
Pass the cursor into :route:`list_folder/continue` to see what's changed
in the folder since your previous query.
has_more:
type: boolean
description: >-
If true, then there are more entries available. Pass the cursor to
:route:`list_folder/continue` to retrieve the rest.
entries:
type: array
description: The files and (direct) subfolders in the folder.
items:
type: object
description: >
Metadata for a file or folder.
name: The last component of the path (including extension). This never
contains a slash.
path_lower: The lowercased full path in the user's Dropbox. This always
starts with a slash. This field will be null if the file or folder is
not mounted.
path_display: The cased path to be used for display purposes only. In
rare instances the casing will not correctly match the user's
filesystem, but this behavior will match the path provided in the Core
API v1, and at least the last path component will have the correct
casing. Changes to only the casing of paths won't be returned by
:route:`list_folder/continue`. This field will be null if the file or
folder is not mounted.
parent_shared_folder_id: Please use
:field:`FileSharingInfo.parent_shared_folder_id` or
:field:`FolderSharingInfo.parent_shared_folder_id` instead.
properties:
parent_shared_folder_id:
type: string
description: >-
Please use :field:`FileSharingInfo.parent_shared_folder_id` or
:field:`FolderSharingInfo.parent_shared_folder_id` instead.
name:
type: string
description: >-
The last component of the path (including extension). This never
contains a slash.
path_display:
type: string
description: >-
The cased path to be used for display purposes only. In rare
instances the casing will not correctly match the user's filesystem,
but this behavior will match the path provided in the Core API v1,
and at least the last path component will have the correct casing.
Changes to only the casing of paths won't be returned by
:route:`list_folder/continue`. This field will be null if the file
or folder is not mounted.
path_lower:
type: string
description: >-
The lowercased full path in the user's Dropbox. This always starts
with a slash. This field will be null if the file or folder is not
mounted.