> ## Documentation Index
> Fetch the complete documentation index at: https://morphik.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# get_folders_details
> Get detailed information about folders with optional document statistics
```python theme={null}
def get_folders_details(
identifiers: Optional[List[str]] = None,
include_document_count: bool = True,
include_status_counts: bool = False,
include_documents: bool = False,
document_filters: Optional[Dict[str, Any]] = None,
document_skip: int = 0,
document_limit: int = 25,
document_fields: Optional[List[str]] = None,
sort_by: Optional[str] = None,
sort_direction: Optional[str] = None,
) -> FolderDetailsResponse
```
```python theme={null}
async def get_folders_details(
identifiers: Optional[List[str]] = None,
include_document_count: bool = True,
include_status_counts: bool = False,
include_documents: bool = False,
document_filters: Optional[Dict[str, Any]] = None,
document_skip: int = 0,
document_limit: int = 25,
document_fields: Optional[List[str]] = None,
sort_by: Optional[str] = None,
sort_direction: Optional[str] = None,
) -> FolderDetailsResponse
```
## Parameters
* `identifiers` (List\[str], optional): List of folder IDs, names, or canonical paths (e.g., `/projects/alpha/specs`). If None, returns all accessible folders.
* `include_document_count` (bool, optional): Include total document count. Defaults to True.
* `include_status_counts` (bool, optional): Include document counts grouped by processing status. Defaults to False.
* `include_documents` (bool, optional): Include paginated document list. Defaults to False.
* `document_filters` (Dict\[str, Any], optional): Optional metadata filters for documents.
* `document_skip` (int, optional): Number of documents to skip for pagination. Defaults to 0.
* `document_limit` (int, optional): Maximum documents per folder. Defaults to 25.
* `document_fields` (List\[str], optional): Optional list of fields to project for documents (dot notation supported).
* `sort_by` (str, optional): Field to sort documents by. Options: "created\_at", "updated\_at", "filename", "external\_id".
* `sort_direction` (str, optional): Sort direction. Options: "asc", "desc".
## Returns
* `FolderDetailsResponse`: Response containing detailed folder information
## Metadata Filters
Filters follow the same JSON syntax across the API. See the [Metadata Filtering guide](/concepts/metadata-filtering) for supported operators and typed comparisons.
## Examples
```python theme={null}
from morphik import Morphik
db = Morphik()
# Get details for all folders with document counts
response = db.get_folders_details()
for folder_detail in response.folders:
folder = folder_detail.folder
doc_info = folder_detail.document_info
print(f"Folder: {folder.name}")
if doc_info and doc_info.total_count is not None:
print(f" Total documents: {doc_info.total_count}")
# Get specific folders with status counts
response = db.get_folders_details(
identifiers=["/projects/reports", "invoices"],
include_status_counts=True,
)
for folder_detail in response.folders:
doc_info = folder_detail.document_info
if doc_info and doc_info.status_counts:
print(f"{folder_detail.folder.name} status breakdown:")
for status, count in doc_info.status_counts.items():
print(f" {status}: {count}")
# Get folders with document list
response = db.get_folders_details(
identifiers=["marketing"],
include_documents=True,
document_limit=10,
sort_by="updated_at",
sort_direction="desc",
)
for folder_detail in response.folders:
doc_info = folder_detail.document_info
if doc_info and doc_info.documents:
print(f"Recent documents in {folder_detail.folder.name}:")
for doc in doc_info.documents:
print(f" - {doc.filename}")
# With document filtering and field projection
response = db.get_folders_details(
include_documents=True,
document_filters={"department": "sales"},
document_fields=["external_id", "filename", "metadata.department"],
document_limit=50,
)
```
```python theme={null}
from morphik import AsyncMorphik
async with AsyncMorphik() as db:
# Get details for all folders with document counts
response = await db.get_folders_details()
for folder_detail in response.folders:
folder = folder_detail.folder
doc_info = folder_detail.document_info
print(f"Folder: {folder.name}")
if doc_info and doc_info.total_count is not None:
print(f" Total documents: {doc_info.total_count}")
# Get specific folders with status counts
response = await db.get_folders_details(
identifiers=["reports", "invoices"],
include_status_counts=True,
)
for folder_detail in response.folders:
doc_info = folder_detail.document_info
if doc_info and doc_info.status_counts:
print(f"{folder_detail.folder.name} status breakdown:")
for status, count in doc_info.status_counts.items():
print(f" {status}: {count}")
# Get folders with document list
response = await db.get_folders_details(
identifiers=["marketing"],
include_documents=True,
document_limit=10,
sort_by="updated_at",
sort_direction="desc",
)
for folder_detail in response.folders:
doc_info = folder_detail.document_info
if doc_info and doc_info.documents:
print(f"Recent documents in {folder_detail.folder.name}:")
for doc in doc_info.documents:
print(f" - {doc.filename}")
# With document filtering and field projection
response = await db.get_folders_details(
include_documents=True,
document_filters={"department": "sales"},
document_fields=["external_id", "filename", "metadata.department"],
document_limit=50,
)
```
## Response Structure
### FolderDetailsResponse
* `folders` (List\[FolderDetails]): List of folder details
### FolderDetails
* `folder` (FolderInfo): Folder information
* `document_info` (FolderDocumentInfo | None): Document statistics and list
`FolderInfo` includes hierarchy fields: `full_path`, `parent_id`, `depth`, and `child_count`, plus description/name metadata.
### FolderDocumentInfo
* `total_count` (int | None): Total document count (when `include_document_count=True`)
* `status_counts` (Dict\[str, int] | None): Document counts by status (when `include_status_counts=True`)
* `documents` (List\[Document] | None): Paginated document list (when `include_documents=True`)
## Notes
* For a lightweight summary, use [`get_folders_summary`](./get_folders_summary) instead.
* The `identifiers` parameter accepts both folder IDs and folder names.
* Document pagination uses `document_skip` and `document_limit` to control the document list.
* Use `document_fields` to reduce response size by projecting only needed fields.