search_query
Search OmniFocus tasks by name or note content. Filter by project, tags, flagged status, or completion, with cursor-based pagination.
Instructions
Full-text search across OmniFocus task names and/or notes. Use for finding tasks by content when you don't know the ID. Supports optional filters (project, tags, flagged, completion status) and cursor pagination. Do NOT use when a known task ID is available (use task_get instead). Returns tasks[] with pagination; safe to call repeatedly; no side effects. Example: search_query({ q: "dentist" }) Example: search_query({ q: "report", projectId: "prj123", completed: "exclude" })
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Search query. Case-insensitive substring match. Empty string matches all tasks (useful with filters). | |
| limit | No | Max results per page (1..500). Default 50. | |
| scope | No | 'name' = search task names only; 'note' = search notes only; 'all' = both. Default 'all'. | |
| cursor | No | Opaque cursor from a previous search_query response. Must use identical filters — changing filters returns a ValidationError. | |
| fields | No | Restrict each returned task to this list of top-level fields (id is always returned). Omit for the full task shape. Empty array returns just id. Unknown names are dropped silently and surface in meta.warnings.WARN_UNKNOWN_FIELDS. Allowed: name, note, noteHtml, projectId, parentId, tagIds, deferDate, deferDateFloating, dueDate, dueDateFloating, estimatedMinutes, flagged, completed, completedAt, dropped, droppedAt, available, blocked, sequential, completedByChildren, repetition, notifications, createdAt, modifiedAt, _links. | |
| tagIds | No | Restrict to tasks carrying ALL of these tags. Get IDs from tag_list. | |
| flagged | No | true = flagged tasks only; false = unflagged only; omit = all. | |
| completed | No | 'exclude' = active tasks only; 'only' = completed only; 'any' = both. Default 'exclude'. | |
| projectId | No | Restrict to tasks in this project. Get the ID from project_list. | |
| includeLinks | No | When true, each task carries a `_links` HATEOAS block (self, project, parent, tags). Default false — the block is omitted to save payload size. Use the task's `id`, `projectId`, `parentId`, and `tagIds` fields directly instead. | |
| maxOutputBytes | No | Cap the serialized byte size of the returned tasks[] array. When the response would exceed this, the server returns as many whole tasks as fit, sets meta.truncatedAtCap=true with meta.bytesReturned and meta.itemsReturned, and returns a pagination cursor that resumes at the first dropped task. Omit for no cap. Values above the server's hard ceiling (~1 MiB) are clamped. A single task larger than the cap is still returned whole so pagination always advances. |