get_folders_details

Get detailed information about folders with optional document statistics

Sync

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

Async

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 for supported operators and typed comparisons.

Examples

Sync

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,
)

Async

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 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.