List Folder | Dropbox API Documentation

import requests
url = "https://api.dropboxapi.com/2/files/list_folder"
payload = {
    "path": "/Homework/math",
    "recursive": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "cursor": "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu",
  "entries": [
    {
      ".tag": "file",
      "client_modified": "2015-05-12T15:50:38Z",
      "content_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "file_lock_info": {
        "created": "2015-05-12T15:50:38Z",
        "is_lockholder": true,
        "lockholder_name": "Imaginary User"
      },
      "has_explicit_shared_members": false,
      "id": "id:a4ayc_80_OEAAAAAAAAAXw",
      "is_downloadable": true,
      "name": "Prime_Numbers.txt",
      "path_display": "/Homework/math/Prime_Numbers.txt",
      "path_lower": "/homework/math/prime_numbers.txt",
      "property_groups": [
        {
          "fields": [
            {
              "name": "Security Policy",
              "value": "Confidential"
            }
          ],
          "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
      ],
      "rev": "a1c10ce0dd78",
      "server_modified": "2015-05-12T15:50:38Z",
      "sharing_info": {
        "modified_by": "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc",
        "parent_shared_folder_id": "84528192421",
        "read_only": true
      },
      "size": 7212
    },
    {
      ".tag": "file",
      "client_modified": "2024-01-15T09:30:00Z",
      "id": "id:a4ayc_80_OEAAAAAAAAAXz",
      "name": "math",
      "path_display": "/Homework/math",
      "path_lower": "/homework/math",
      "property_groups": [
        {
          "fields": [
            {
              "name": "Security Policy",
              "value": "Confidential"
            }
          ],
          "template_id": "ptid:1a5n2i6d3OYEAAAAAAAAAYa"
        }
      ],
      "rev": "string",
      "server_modified": "2024-01-15T09:30:00Z",
      "sharing_info": {
        "parent_shared_folder_id": "84528192421",
        "read_only": false
      },
      "size": 1
    }
  ],
  "has_more": false
}

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)

Starts returning the contents of a folder. If the result's `ListFolderResult.has_more` field is true, call [list_folder/continue](api:dropbox-api:POST/2/files/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](api:dropbox-api:POST/2/files/list_folder) or [list_folder/continue](api:dropbox-api:POST/2/files/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](https://docs.dropboxapi.com/dropbox-api/docs/technical-reference/request-response-formats#rpc-endpoints) **Authentication:** [App](https://docs.dropboxapi.com/dropbox-api/docs/auth-types#app-authentication), [User](https://docs.dropboxapi.com/dropbox-api/docs/auth-types#user-authentication), [Dropbox-API-Select-Admin (Whole Team)](https://docs.dropboxapi.com/dropbox-api/docs/auth-types#admin-authentication-via-dropbox-api-select-admin)

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.

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.

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](https://docs.dropboxapi.com/dropbox-api/docs/oauth#testing-with-a-generated-token).

Headers

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.

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.

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.

shared_linkobject or nullOptional

A shared link to list the contents of. If the link is password-protected, the password must be provided. If this field is present, ListFolderArg.path will be relative to root of the shared link. Only non-recursive mode is supported for shared link.

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.

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

Required scope: files.metadata.read

Endpoint format: RPC

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