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

# search_documents

> Search for documents by name or filename

> [tab] Sync
>
> ```python theme={null}
> def search_documents(
>     query: str,
>     limit: int = 10,
>     filters: Optional[Dict[str, Any]] = None,
>     folder_name: Optional[Union[str, List[str]]] = None,
>     folder_depth: Optional[int] = None,
>     end_user_id: Optional[str] = None,
> ) -> List[Document]
> ```

> [tab] Async
>
> ```python theme={null}
> async def search_documents(
>     query: str,
>     limit: int = 10,
>     filters: Optional[Dict[str, Any]] = None,
>     folder_name: Optional[Union[str, List[str]]] = None,
>     folder_depth: Optional[int] = None,
>     end_user_id: Optional[str] = None,
> ) -> List[Document]
> ```

## Parameters

* `query` (str): Search query for document names/filenames
* `limit` (int, optional): Maximum number of documents to return. Defaults to 10.
* `filters` (Dict\[str, Any], optional): Optional metadata filters
* `folder_name` (str | List\[str], optional): Optional folder scope (canonical path or list of paths/names)
* `folder_depth` (int, optional): Folder scope depth. `None`/`0` = exact match, `-1` = include all descendants, `n > 0` = include descendants up to `n` levels deep.
* `end_user_id` (str, optional): Optional end-user scope

## Returns

* `List[Document]`: List of matching documents

## Metadata Filters

Filters follow the same JSON syntax across the API. See the [Metadata Filtering guide](https://morphik.ai/docs/concepts/metadata-filtering.md) for supported operators and typed comparisons. Example:

```python theme={null}
filters = {
    "$and": [
        {"department": {"$eq": "research"}},
        {"priority": {"$gte": 40}},
    ]
}

docs = db.search_documents("report", filters=filters)
```

## Examples

> [tab] Sync
>
> ```python theme={null}
> from morphik import Morphik
>
> db = Morphik()
>
> # Basic document name search
> docs = db.search_documents("quarterly report")
> for doc in docs:
>     print(f"{doc.external_id}: {doc.filename}")
>
> # Search with limit and filters
> docs = db.search_documents(
>     query="invoice",
>     limit=20,
>     filters={"department": "finance"},
> )
>
> # Search within specific folders
> docs = db.search_documents(
>     query="contract",
>     folder_name="/projects/legal",
>     folder_depth=-1,
> )
>
> # Search scoped to an end user
> docs = db.search_documents(
>     query="notes",
>     end_user_id="user_456",
> )
> ```

> [tab] Async
>
> ```python theme={null}
> from morphik import AsyncMorphik
>
> async with AsyncMorphik() as db:
>     # Basic document name search
>     docs = await db.search_documents("quarterly report")
>     for doc in docs:
>         print(f"{doc.external_id}: {doc.filename}")
>
>     # Search with limit and filters
>     docs = await db.search_documents(
>         query="invoice",
>         limit=20,
>         filters={"department": "finance"},
>     )
>
>     # Search within specific folders
>     docs = await db.search_documents(
>         query="contract",
>         folder_name="/projects/legal",
>         folder_depth=-1,
>     )
>
>     # Search scoped to an end user
>     docs = await db.search_documents(
>         query="notes",
>         end_user_id="user_456",
>     )
> ```

## Notes

* This method searches document names and filenames, not document content. For content-based search, use [`retrieve_chunks`](./retrieve_chunks) or [`retrieve_docs`](./retrieve_docs).
* The `folder_name` parameter accepts a canonical path (leading slash optional) or a list of paths/names; combine with `folder_depth` to include descendants.
* Results are returned sorted by relevance to the search query.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.