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

# notes_search

> One fast search of the person's notes, files and synced apps.

> [!NOTE]
>
> Free · Your key and project keys

Searches for the words exactly as written: one search, no planning and no reading, so it is fast and free. Search again with other words if the first try misses. Read one result in full with [notes\_read](/dev/docs/api-reference/tools/notes-read.md).

Call it at `POST /platform/v1/me/tools/notes_search` or, for one of your app's users, `POST /platform/v1/users/{uid}/tools/notes_search`. On MCP, your AI tool calls `notes_search` with the same arguments.

## Arguments

Send these inside `arguments`.

**query** `string` *required*

What to search for.

**filters** `object` (default: null)

All optional: `max_results` (1-60, default 14), `exclude_ids` (ids to leave out), `include_chatter` (mail, chat and calendar too; default `true`), `apps` (only results from these connected apps, like `["gmail", "slack"]`).

## Returns

The tool's answer comes back under `result`.

**notes** `object[]`

Best first. Each has `id`, `title`, `where`, `passages`, `score`, `source`, `type`, `date` and `via`.

**queries** `string[]`

The searches that ran.

**timed\_out** `boolean`

`true` when the search ran out of time.

```bash Your key theme={"system"}
curl https://api.constella.app/platform/v1/me/tools/notes_search \
  -H "Authorization: Bearer $CONSTELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"query": "pricing", "filters": {"apps": ["gmail"]}}}'
```

```bash Project key theme={"system"}
curl https://api.constella.app/platform/v1/users/u_123/tools/notes_search \
  -H "Authorization: Bearer $CONSTELLA_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"query": "pricing", "filters": {"apps": ["gmail"]}}}'
```

```python Python theme={"system"}
import os, requests

r = requests.post(
    "https://api.constella.app/platform/v1/me/tools/notes_search",
    headers={"Authorization": f"Bearer {os.environ['CONSTELLA_API_KEY']}", "X-Constella-Client": "my-script"},
    json={"arguments": {"query": "pricing", "filters": {"apps": ["gmail"]}}},
)
print(r.json()["result"])
```

```javascript JavaScript theme={"system"}
const res = await fetch("https://api.constella.app/platform/v1/me/tools/notes_search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CONSTELLA_API_KEY}`,
    "X-Constella-Client": "my-script",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"arguments": {"query": "pricing", "filters": {"apps": ["gmail"]}}}),
});
const { result } = await res.json();
```

```json 200 theme={"system"}
{
  "result": {
    "notes": [
      {
        "id": "9f2c...",
        "title": "Re: pricing for the team plan",
        "type": "email",
        "source": "gmail",
        "date": "2026-11-02",
        "score": 0.71
      }
    ],
    "queries": [
      "pricing"
    ],
    "timed_out": false
  }
}
```


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