> ## Documentation Index
> Fetch the complete documentation index at: https://surfacedocs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Documents

> Find documents by title or tag with search_documents()

# Search Documents

## search\_documents()

Search your documents by title prefix and/or tag. Results are scoped to the authenticated user.

```python theme={null}
from surfacedocs import SurfaceDocs

docs = SurfaceDocs()

# Search by title prefix
results = docs.search_documents(query="API")

# Search by tag
results = docs.search_documents(tag="guide")

# Combine title + tag
results = docs.search_documents(query="Auth", tag="security")

# Scope to a folder
results = docs.search_documents(query="setup", folder_id="fld_abc123")

for result in results:
    print(f"{result.title} → {result.url}")
```

**Parameters:**

| Parameter   | Type  | Required | Description                                   |
| ----------- | ----- | -------- | --------------------------------------------- |
| `query`     | `str` | No\*     | Title prefix to search for (case-insensitive) |
| `tag`       | `str` | No\*     | Exact tag to match                            |
| `folder_id` | `str` | No       | Folder ID to scope results                    |
| `limit`     | `int` | No       | Max results to return (default: 20, max: 50)  |
| `offset`    | `int` | No       | Number of results to skip for pagination      |

<Note>At least one of `query` or `tag` is required.</Note>

**Returns:** `list[SearchResult]`

**Raises:** `ValidationError` if neither `query` nor `tag` is provided.

## SearchResult

Each result contains document metadata (no blocks — use [`get_document()`](/sdk/read-documents) to fetch full content).

```python theme={null}
result.id               # "doc_abc123"
result.url              # "https://app.surfacedocs.dev/d/doc_abc123"
result.folder_id        # "fld_xyz"
result.title            # "API Documentation"
result.content_type     # "markdown"
result.block_count      # 15
result.visibility       # "private"
result.metadata         # {"tags": ["api", "guide"], "source": "claude"}
result.current_version  # 3
result.created_at       # "2024-01-01T00:00:00Z"
result.updated_at       # "2024-01-02T00:00:00Z"
```

## Pagination

Use `limit` and `offset` for paginating through results:

```python theme={null}
# First page
page1 = docs.search_documents(query="report", limit=10, offset=0)

# Second page
page2 = docs.search_documents(query="report", limit=10, offset=10)
```

## Examples

### Find all documents tagged by source

```python theme={null}
# Find everything generated by Claude
claude_docs = docs.search_documents(tag="claude")

# Find everything from a specific pipeline
pipeline_docs = docs.search_documents(tag="weekly-report")
```

### Search within a project folder

```python theme={null}
results = docs.search_documents(
    query="architecture",
    folder_id="fld_project_x",
    limit=5,
)
```