---
title: "search"
description: "Search Cadence: inputs, outputs, permissions, examples, and errors."
canonical_url: https://cadence-me.com/developers/tools/search
last_updated: 2026-10-18
status: stable
source: src/data/developer-reference.json
---

# search

Searches the user's Behaviors (titles, descriptions, archive notes), Occurrence notes, and day notes by text. Returns ids for `fetch` and links into the Cadence web app. Use it to find a habit, routine, or note by keyword. A day note is the user's one note about a whole calendar date (for example "Travel day" or "Sick"). It is not an Occurrence note, has no status, and never changes Completed, Not Completed, Unresolved, Needs decision, adherence, or reminders.

## Permission and annotations

Required scope: `cadence.read`. Contract 1.7.0; available since 1.0.0.

- `title`: "Search Cadence"
- `readOnlyHint`: true
- `destructiveHint`: false
- `idempotentHint`: true
- `openWorldHint`: false

Reads account data and changes nothing, so readOnlyHint is true. Claude runs read-only tools without per-call confirmation, and OpenAI asks for readOnlyHint on every read. openWorldHint is false because the tool reaches only the user's own Cadence account.

## Input

Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.

| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
| ` query ` | yes | string | Search text.; minLength: ` 1 `; maxLength: ` 200 `; pattern: <code>&#92;&#83;</code> |

## Output

Required means required within the containing object. Variant fields apply only to that variant; children of nullable values apply when non-null. Unknown fields are rejected.

| Field | Required | Type | Meaning and constraints |
|---|---|---|---|
| ` results ` | yes | array | maxItems: ` 20 ` |
| ` results[] ` | yes | object |  |
| ` results[].id ` | yes | string | Result id from `search`: `behavior:<uuid>`, `occurrence:<uuid>`, or `day_note:<uuid>`.; maxLength: ` 64 `; pattern: ` ^(behavior\|occurrence\|day_note):[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ` |
| ` results[].title ` | yes | string |  |
| ` results[].url ` | yes | string | Link to the record in the Cadence web app.; format: ` uri `; maxLength: ` 2048 `; pattern: ` ^https:// ` |

## Example call

Synthetic contract fixture. Replace identifiers and dates with records returned for your account. This is the SDK tools/call payload, not a complete HTTP request.

```json
{
  "name": "search",
  "arguments": {
    "query": "walk"
  }
}
```

## Example result

Synthetic success data from a contract fixture, shown as structuredContent. Input and output examples validate independently; they are not a recorded transaction.

```json
{
  "results": [
    {
      "id": "behavior:00000001-1111-4111-8111-000000000001",
      "title": "Morning walk",
      "url": "https://app.cadence-me.com/behaviors?behavior=00000001-1111-4111-8111-000000000001"
    },
    {
      "id": "occurrence:00000005-1111-4111-8111-000000000005",
      "title": "Morning walk on 2026-10-18",
      "url": "https://app.cadence-me.com/timeline?date=2026-10-18&occurrence=00000005-1111-4111-8111-000000000005"
    },
    {
      "id": "day_note:00000009-1111-4111-8111-000000000009",
      "title": "Day note for 2026-10-18",
      "url": "https://app.cadence-me.com/timeline"
    }
  ]
}
```

## Errors

- `invalid_input`: The input does not match the tool's schema or rules. `field_errors` names each problem.
- `authentication_required`: The access token is missing, expired, revoked, or issued for another resource. Reconnect Cadence.
- `rate_limited`: Too many requests for this connection. Retry after `retry_after_seconds`.
- `service_unavailable`: Cadence integrations are temporarily unavailable.
- `internal_error`: Cadence could not complete the request. Nothing is assumed to have changed; retry once with the same `idempotency_key`.

Output size limits can also return `limit_exceeded`. See [error handling](/developers/errors), [limits](/developers/limits), and [safe retries](/developers/idempotency).
